> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.oryxa.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations API: Connect Commerce Platforms

> Connect Shopify, Amazon, and other commerce platforms via OAuth. Push products to integrations and receive inbound events through HMAC-verified webhooks.

The Integrations API lets you connect Synq to third-party commerce platforms — such as Shopify, WooCommerce, or Amazon — using an OAuth flow. Once connected, you can push product data to those platforms and receive inbound webhook events from them. Synq handles the credential storage and connection lifecycle; you only need to store the resulting `connection_id`.

<Note>
  All requests **except** `POST /unified/webhook` require three headers: `Authorization: Bearer YOUR_TOKEN`, `X-Tenant-ID: YOUR_TENANT_ID`, and `X-Org-ID: YOUR_ORG_ID`. The webhook endpoint is public and uses HMAC signature verification instead.
</Note>

***

## Get OAuth authorization URL

Generate the OAuth URL your users should visit to authorize a new integration. Redirect them to the returned `auth_url`; Synq handles the OAuth callback automatically and generates a `connection_id` you can save with the callback endpoint below.

**`POST /api/v1/integrations/auth-url`**

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  UUID of your tenant. This is embedded in the OAuth `state` parameter to tie the callback back to your account.
</ParamField>

<ParamField header="X-Org-ID" type="string" required>
  UUID of your organization.
</ParamField>

### Response

<ResponseField name="auth_url" type="string">
  The full OAuth authorization URL. Redirect your user's browser to this URL to start the connection flow.
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.synq.app/api/v1/integrations/auth-url \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  {
    "auth_url": "https://api.unified.to/integration/auth?state=YOUR_TENANT_ID&workspace_id=ws_synq_prod&category=commerce"
  }
  ```
</CodeGroup>

***

## Save a connection

After a user completes the OAuth flow, the provider returns a `connection_id`. Call this endpoint to persist that connection in Synq and activate background sync for the platform.

**`POST /api/v1/integrations/callback`**

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  UUID of your tenant.
</ParamField>

<ParamField header="X-Org-ID" type="string" required>
  UUID of your organization.
</ParamField>

### Body

<ParamField body="connection_id" type="string" required>
  The `connection_id` returned by the OAuth provider after authorization completion.
</ParamField>

<ParamField body="category" type="string">
  Integration category. Use `commerce` for storefronts and marketplaces, or `accounting` for accounting platforms. Defaults to `commerce`.
</ParamField>

<ParamField body="provider" type="string">
  Provider name, e.g. `shopify`, `woocommerce`, or `amazon`. Used as a display name for the connection.
</ParamField>

### Response

Returns `201 Created` on success.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.synq.app/api/v1/integrations/callback \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "connection_id": "conn_3Xabc...",
      "category": "commerce",
      "provider": "shopify"
    }'
  ```

  ```json Response theme={null}
  {
    "status": "success",
    "message": "Integration secured"
  }
  ```
</CodeGroup>

***

## List connections

Retrieve all active integrations for your tenant and organization.

**`GET /api/v1/integrations/connections`**

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  UUID of your tenant.
</ParamField>

<ParamField header="X-Org-ID" type="string" required>
  UUID of your organization.
</ParamField>

### Response

<ResponseField name="connections" type="array">
  Array of active connection objects.

  <Expandable title="Connection fields">
    <ResponseField name="id" type="string">Synq-internal UUID for this connection.</ResponseField>
    <ResponseField name="unified_connection_id" type="string">The provider `connection_id` issued during OAuth.</ResponseField>
    <ResponseField name="provider" type="string">Integration provider, e.g. `shopify`.</ResponseField>
    <ResponseField name="status" type="string">Connection status, e.g. `ACTIVE`.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.synq.app/api/v1/integrations/connections \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  {
    "connections": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "unified_connection_id": "conn_3Xabc...",
        "provider": "shopify",
        "status": "ACTIVE",
        "created_at": "2024-05-01T09:00:00Z",
        "updated_at": "2024-05-01T09:00:00Z"
      }
    ]
  }
  ```
</CodeGroup>

***

## Push a product to integrations

Enqueue an asynchronous job to push a product record to all active integrations for your tenant. The platform fans the job out to every connected provider in the background.

**`POST /unified/sync/push/product`**

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  UUID of your tenant.
</ParamField>

<ParamField header="X-Org-ID" type="string" required>
  UUID of your organization.
</ParamField>

### Body

<ParamField body="productId" type="string" required>
  UUID of the Synq product to push.
</ParamField>

<ParamField body="action" type="string" required>
  The sync action to perform. Use `UPSERT` to create or update the product on the remote platform, or `DELETE` to remove it.
</ParamField>

### Response

Returns `202 Accepted` immediately. The push job runs asynchronously.

<ResponseField name="status" type="string">
  Always `queued` on a successful `202` response.
</ResponseField>

<CodeGroup>
  ```bash cURL — Upsert theme={null}
  curl -X POST https://api.synq.app/unified/sync/push/product \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "productId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "action": "UPSERT"
    }'
  ```

  ```bash cURL — Delete theme={null}
  curl -X POST https://api.synq.app/unified/sync/push/product \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "productId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "action": "DELETE"
    }'
  ```

  ```json Response theme={null}
  {
    "status": "queued"
  }
  ```
</CodeGroup>

***

## Inbound webhook

Receive real-time events from connected platforms (e.g. new Shopify orders, inventory updates). Synq verifies every inbound payload using an HMAC-SHA256 signature before processing it.

**`POST /unified/webhook`**

<Note>
  This endpoint is **public** — it does not require `Authorization`, `X-Tenant-ID`, or `X-Org-ID` headers. Security is enforced entirely through the `X-Unified-Signature` HMAC header. Requests with an invalid or missing signature are rejected with `401 Unauthorized`.
</Note>

### Headers

<ParamField header="X-Unified-Signature" type="string" required>
  HMAC-SHA256 hex digest of the raw request body, signed with your webhook secret. Synq rejects the request if this does not match.
</ParamField>

### Body

<ParamField body="connection_id" type="string" required>
  The provider `connection_id` that originated this event. Must match an active connection in Synq.
</ParamField>

<ParamField body="event" type="string" required>
  Event type from the upstream platform, e.g. `order.created` or `product.updated`.
</ParamField>

<ParamField body="data" type="object" required>
  Raw event payload from the upstream platform.
</ParamField>

Synq looks up the internal connection record matching `connection_id`, validates it is `ACTIVE`, and persists the event to the outbox for downstream processing. Returns `200 OK` on success.

<CodeGroup>
  ```bash cURL — Example inbound webhook (test) theme={null}
  # In practice your platform sends this; shown here for testing
  curl -X POST https://api.synq.app/unified/webhook \
    -H "Content-Type: application/json" \
    -H "X-Unified-Signature: <hmac-sha256-hex>" \
    -d '{
      "connection_id": "conn_3Xabc...",
      "event": "order.created",
      "data": {
        "external_order_id": "shopify-order-9001",
        "total": 205.27,
        "currency": "USD"
      }
    }'
  ```
</CodeGroup>

***

## UCP catalog feed

Retrieve a redirect to your tenant's Unified Commerce Profile (UCP) catalog feed. This endpoint issues a `302 Found` redirect to a static JSON-LD file that describes your full product catalog in a machine-readable format. It is designed for AI shopping agents and Merchant Center integrations that require a stable, authenticated URL to crawl your catalog without placing load on the primary API.

**`GET /api/v1/ucp/catalog.json`**

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider. The token must be linked to a valid tenant.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  UUID of your tenant.
</ParamField>

<ParamField header="X-Org-ID" type="string" required>
  UUID of your organization.
</ParamField>

### Response

Returns `302 Found` with a `Location` header pointing to your tenant's catalog JSON-LD file. The redirect URL is dynamic and should not be cached — always call this endpoint to get the current feed URL.

<CodeGroup>
  ```bash cURL theme={null}
  curl -v https://api.synq.app/api/v1/ucp/catalog.json \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```text Response theme={null}
  HTTP/1.1 302 Found
  Location: https://storage.googleapis.com/ucp-feeds/tenant_YOUR_TENANT_ID_ucp_catalog.json
  Cache-Control: no-cache, no-store, must-revalidate
  ```
</CodeGroup>