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

# Set Up Sales Channels for Your Storefront

> Create and manage sales channels in Synq to represent distinct storefronts, B2B portals, or marketplaces — each with its own currency and order context.

A sales channel in Synq represents a distinct selling context — your main e-commerce website, a wholesale B2B portal, a regional marketplace, or any other surface where customers place orders. Every channel carries a name and an ISO currency code, and every order in Synq is stamped with the `channel_id` of the channel it originated from, giving you clean segmentation for reporting, fulfillment, and pricing logic.

## Authentication

All Sales Channel endpoints require three headers:

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

<Note>
  Creating a sales channel requires an **Admin** or **Editor** role. Listing channels is available to all authenticated roles.
</Note>

***

## List your sales channels

Retrieve all channels configured for your organization and tenant.

```http theme={null}
GET /api/v1/channels
```

**Example request**

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.synq.com/api/v1/channels \
    -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/channels", {
    headers: {
      Authorization: "Bearer TOKEN",
      "X-Tenant-ID": "a1b2c3d4-0000-0000-0000-000000000001",
      "X-Org-ID": "a1b2c3d4-0000-0000-0000-000000000002",
    },
  });
  const { channels } = await response.json();
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "channels": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "name": "Main Storefront",
      "currency": "USD",
      "active": true,
      "created_at": "2024-06-01T10:00:00Z",
      "updated_at": "2024-06-01T10:00:00Z"
    },
    {
      "id": "c9bf9e57-1685-4c89-bafb-ff5af830be8a",
      "name": "B2B Portal",
      "currency": "EUR",
      "active": true,
      "created_at": "2024-07-15T08:30:00Z",
      "updated_at": "2024-07-15T08:30:00Z"
    }
  ]
}
```

<ResponseField name="channels" type="array">
  Array of sales channel objects.

  <ResponseField name="id" type="string">
    UUID of the sales channel.
  </ResponseField>

  <ResponseField name="name" type="string">
    Display name for the channel.
  </ResponseField>

  <ResponseField name="currency" type="string">
    Three-letter ISO 4217 currency code (e.g. `USD`, `EUR`, `GBP`).
  </ResponseField>

  <ResponseField name="active" type="boolean">
    Whether the channel is currently accepting orders.
  </ResponseField>

  <ResponseField name="created_at" type="string">
    ISO 8601 timestamp when the channel was created.
  </ResponseField>

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

***

## Create a sales channel

Create a new sales channel for your organization. The `name` field is required; `currency` defaults to `USD` if omitted, and `active` defaults to `true`.

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

**Request body**

<ParamField body="name" type="string" required>
  A human-readable name for the channel (e.g. `"North America Storefront"`). Must not be empty.
</ParamField>

<ParamField body="currency" type="string">
  A three-letter ISO 4217 currency code. Defaults to `USD` if not provided.
</ParamField>

<ParamField body="active" type="boolean">
  Whether the channel should start in an active state. Defaults to `true`.
</ParamField>

**Example request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.synq.com/api/v1/channels \
    -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 '{
      "name": "APAC Marketplace",
      "currency": "AUD",
      "active": true
    }'
  ```

  ```js JavaScript theme={null}
  const response = await fetch("https://api.synq.com/api/v1/channels", {
    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({
      name: "APAC Marketplace",
      currency: "AUD",
      active: true,
    }),
  });
  const channel = await response.json();
  ```
</CodeGroup>

**Example response** — `201 Created`

```json theme={null}
{
  "id": "3d721c8e-4a11-4b0e-9f38-abc123def456",
  "name": "APAC Marketplace",
  "currency": "AUD",
  "active": true,
  "created_at": "2024-09-01T12:00:00Z",
  "updated_at": "2024-09-01T12:00:00Z"
}
```

<ResponseField name="id" type="string">
  UUID of the newly created sales channel. Store this — you will need it as the `channel_id` when creating orders.
</ResponseField>

***

## Associate orders with a channel

When you create an order through the Synq Orders API, pass the `channel_id` field to link it to the correct sales channel. The value must be the `id` returned when you created (or listed) the channel.

```json theme={null}
{
  "channel_id": "3d721c8e-4a11-4b0e-9f38-abc123def456",
  "currency": "AUD",
  "items": [...]
}
```

This association enables per-channel reporting, currency-aware pricing, and channel-scoped fulfillment rules across your Synq workspace.

<Tip>
  Use descriptive channel names that reflect the selling surface (e.g. `"EU Wholesale"`, `"Amazon US"`, `"DTC Website"`) — these names appear in Synq dashboards and audit logs.
</Tip>