> ## 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.

# Connect Your Commerce Tools to Synq

> Connect Shopify, WooCommerce, Amazon, and 100+ commerce platforms to Synq via OAuth, then push and sync products across all your storefronts automatically.

Synq connects to over 100 commerce platforms — including Shopify, WooCommerce, Amazon, BigCommerce, and more — through a secure OAuth flow. Once connected, Synq continuously syncs your product catalog and orders across every storefront, giving you a single source of truth for your commerce operations.

## Authentication

All Integration endpoints require these headers on every request:

| Header          | Description               |
| --------------- | ------------------------- |
| `Authorization` | `Bearer <your API token>` |
| `X-Tenant-ID`   | Your tenant UUID          |
| `X-Org-ID`      | Your organization UUID    |

***

## Connect a commerce platform

Use the following OAuth flow to connect a new storefront or marketplace to Synq.

<Steps>
  ### Get the authorization URL

  Call `POST /api/v1/integrations/auth-url` to receive a unique OAuth URL scoped to your tenant. Redirect your user to this URL to begin the authorization flow on the target platform.

  ```http theme={null}
  POST /api/v1/integrations/auth-url
  ```

  **Example request**

  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST https://api.synq.com/api/v1/integrations/auth-url \
      -H "Authorization: Bearer TOKEN" \
      -H "X-Tenant-ID: a1b2c3d4-0000-0000-0000-000000000001" \
      -H "X-Org-ID: a1b2c3d4-0000-0000-0000-000000000002"
    ```

    ```js JavaScript theme={null}
    const response = await fetch(
      "https://api.synq.com/api/v1/integrations/auth-url",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer TOKEN",
          "X-Tenant-ID": "a1b2c3d4-0000-0000-0000-000000000001",
          "X-Org-ID": "a1b2c3d4-0000-0000-0000-000000000002",
        },
      }
    );
    const { auth_url } = await response.json();
    ```
  </CodeGroup>

  **Example response**

  ```json theme={null}
  {
    "auth_url": "https://api.unified.to/integration/auth?category=commerce&state=a1b2c3d4-0000-0000-0000-000000000001"
  }
  ```

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

  ### Redirect your user to authorize the connection

  Send your user to the `auth_url` returned in step 1. They will be presented with a list of supported commerce platforms (Shopify, WooCommerce, Amazon, etc.) and prompted to authorize Synq's access.

  After the user grants access, Synq completes the OAuth handshake and returns a `connection_id` to your configured redirect URI along with the `category` and `provider` of the connected platform.

  <Tip>
    Store the returned `connection_id` in your application's session or state — you'll need it in the next step to complete the connection registration in Synq.
  </Tip>

  ### Save the connection to Synq

  After authorization, call `POST /api/v1/integrations/callback` with the `connection_id` returned in the OAuth callback. Synq verifies the connection and registers it against your tenant so that product sync and webhook events work automatically.

  ```http theme={null}
  POST /api/v1/integrations/callback
  Content-Type: application/json
  ```

  **Request body**

  <ParamField body="connection_id" type="string" required>
    The connection ID returned after the user completes OAuth authorization. Must not be empty.
  </ParamField>

  <ParamField body="category" type="string">
    The integration category. Defaults to `"commerce"`. Use `"accounting"` for accounting platforms.
  </ParamField>

  <ParamField body="provider" type="string">
    The platform name in lowercase (e.g. `"shopify"`, `"woocommerce"`, `"amazon"`). Used as a fallback identifier in non-production environments.
  </ParamField>

  **Example request**

  <CodeGroup>
    ```bash cURL theme={null}
    curl -X POST https://api.synq.com/api/v1/integrations/callback \
      -H "Authorization: Bearer TOKEN" \
      -H "X-Tenant-ID: a1b2c3d4-0000-0000-0000-000000000001" \
      -H "X-Org-ID: a1b2c3d4-0000-0000-0000-000000000002" \
      -H "Content-Type: application/json" \
      -d '{
        "connection_id": "conn_shopify_8f3a2b",
        "category": "commerce",
        "provider": "shopify"
      }'
    ```

    ```js JavaScript theme={null}
    const response = await fetch(
      "https://api.synq.com/api/v1/integrations/callback",
      {
        method: "POST",
        headers: {
          Authorization: "Bearer TOKEN",
          "X-Tenant-ID": "a1b2c3d4-0000-0000-0000-000000000001",
          "X-Org-ID": "a1b2c3d4-0000-0000-0000-000000000002",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          connection_id: "conn_shopify_8f3a2b",
          category: "commerce",
          provider: "shopify",
        }),
      }
    );
    const result = await response.json();
    ```
  </CodeGroup>

  **Example response** — `201 Created`

  ```json theme={null}
  {
    "status": "success",
    "message": "Integration secured"
  }
  ```

  ### Verify your connections

  Confirm the integration registered correctly by listing all active connections for your tenant.

  ```http theme={null}
  GET /api/v1/integrations/connections
  ```

  **Example request**

  <CodeGroup>
    ```bash cURL theme={null}
    curl https://api.synq.com/api/v1/integrations/connections \
      -H "Authorization: Bearer TOKEN" \
      -H "X-Tenant-ID: a1b2c3d4-0000-0000-0000-000000000001" \
      -H "X-Org-ID: a1b2c3d4-0000-0000-0000-000000000002"
    ```

    ```js JavaScript theme={null}
    const response = await fetch(
      "https://api.synq.com/api/v1/integrations/connections",
      {
        headers: {
          Authorization: "Bearer TOKEN",
          "X-Tenant-ID": "a1b2c3d4-0000-0000-0000-000000000001",
          "X-Org-ID": "a1b2c3d4-0000-0000-0000-000000000002",
        },
      }
    );
    const { connections } = await response.json();
    ```
  </CodeGroup>

  **Example response**

  ```json theme={null}
  {
    "connections": [
      {
        "id": "7e9d1f3c-aaaa-4d2e-b001-112233445566",
        "unified_connection_id": "conn_shopify_8f3a2b",
        "provider": "shopify",
        "status": "ACTIVE",
        "created_at": "2024-09-01T12:05:00Z",
        "updated_at": "2024-09-01T12:05:00Z"
      }
    ]
  }
  ```

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

    <ResponseField name="id" type="string">
      Synq's internal UUID for this connection.
    </ResponseField>

    <ResponseField name="unified_connection_id" type="string">
      The connection ID issued during the OAuth flow.
    </ResponseField>

    <ResponseField name="provider" type="string">
      Lowercase name of the connected platform (e.g. `"shopify"`, `"woocommerce"`).
    </ResponseField>

    <ResponseField name="status" type="string">
      Current connection status. `ACTIVE` means the connection is live and syncing.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp when the connection was first registered.
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO 8601 timestamp of the last status change.
    </ResponseField>
  </ResponseField>
</Steps>

***

## Sync products to connected platforms

Once you have at least one active connection, push any product in your Synq catalog to all connected storefronts with a single API call.

```http theme={null}
POST /unified/sync/push/product
Content-Type: application/json
```

**Request body**

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

<ParamField body="action" type="string" required>
  Sync action to perform. Use `"UPSERT"` to create or update the product on all connected storefronts, or `"DELETE"` to remove it from all connected storefronts.
</ParamField>

**Example request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.synq.com/unified/sync/push/product \
    -H "Authorization: Bearer TOKEN" \
    -H "X-Tenant-ID: a1b2c3d4-0000-0000-0000-000000000001" \
    -H "X-Org-ID: a1b2c3d4-0000-0000-0000-000000000002" \
    -H "Content-Type: application/json" \
    -d '{
      "productId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "action": "UPSERT"
    }'
  ```

  ```js JavaScript theme={null}
  const response = await fetch(
    "https://api.synq.com/unified/sync/push/product",
    {
      method: "POST",
      headers: {
        Authorization: "Bearer TOKEN",
        "X-Tenant-ID": "a1b2c3d4-0000-0000-0000-000000000001",
        "X-Org-ID": "a1b2c3d4-0000-0000-0000-000000000002",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        productId: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        action: "UPSERT",
      }),
    }
  );
  const result = await response.json();
  // { "status": "queued" }
  ```
</CodeGroup>

**Example response** — `202 Accepted`

```json theme={null}
{
  "status": "queued"
}
```

<Note>
  The `action` field accepts two values: `"UPSERT"` (create or update the product on every connected storefront) and `"DELETE"` (remove the product from every connected storefront).

  Product sync is **asynchronous**. A `202 Accepted` response means Synq has queued the sync job — the actual push to each connected storefront happens in the background. Synq fans out the update to every active connection for your tenant with automatic retries and exponential backoff on transient errors.
</Note>