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

# Sales Channels API: Manage Storefronts

> Create and list sales channels such as storefronts, marketplaces, and POS locations. Each channel has its own currency and active state.

Sales channels in Synq represent the distinct storefronts, marketplaces, or point-of-sale locations through which you sell your products. Associating orders and products with channels lets you report on performance per sales surface and apply channel-specific pricing or catalog rules. You can list your existing channels or create new ones through this API.

<Note>
  All requests require three headers: `Authorization: Bearer YOUR_TOKEN`, `X-Tenant-ID: YOUR_TENANT_ID`, and `X-Org-ID: YOUR_ORG_ID`. Creating a channel requires the `Admin` or `Editor` role.
</Note>

***

## List sales channels

Retrieve all sales channels for your tenant and organization.

**`GET /api/v1/channels`**

### 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="channels" type="array">
  Array of sales channel objects.

  <Expandable title="Channel fields">
    <ResponseField name="id" type="string">UUID of the sales channel.</ResponseField>
    <ResponseField name="name" type="string">Display name of the channel.</ResponseField>
    <ResponseField name="currency" type="string">ISO 4217 currency code for this channel, e.g. `USD`.</ResponseField>
    <ResponseField name="active" type="boolean">Whether the channel is currently 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/channels \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  {
    "channels": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "Main Web Storefront",
        "currency": "USD",
        "active": true,
        "created_at": "2024-01-15T09:00:00Z",
        "updated_at": "2024-01-15T09:00:00Z"
      },
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "New York Flagship POS",
        "currency": "USD",
        "active": true,
        "created_at": "2024-03-10T12:30:00Z",
        "updated_at": "2024-03-10T12:30:00Z"
      },
      {
        "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
        "name": "European Storefront",
        "currency": "EUR",
        "active": false,
        "created_at": "2024-04-22T08:45:00Z",
        "updated_at": "2024-05-01T11:00:00Z"
      }
    ]
  }
  ```
</CodeGroup>

***

## Create a sales channel

Create a new sales channel. You must have the `Admin` or `Editor` role to call this endpoint.

**`POST /api/v1/channels`**

### 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="name" type="string" required>
  Display name of the channel, e.g. `European Storefront`.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 three-letter currency code, e.g. `USD`, `EUR`, or `GBP`. Defaults to `USD` if omitted. Must be exactly 3 characters.
</ParamField>

<ParamField body="active" type="boolean">
  Whether the channel should be active at creation. Defaults to `true`.
</ParamField>

### Response

Returns `201 Created` with the new channel object.

<ResponseField name="id" type="string">UUID of the created channel.</ResponseField>
<ResponseField name="name" type="string">Display name.</ResponseField>
<ResponseField name="currency" type="string">ISO 4217 currency code.</ResponseField>
<ResponseField name="active" type="boolean">Active state.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>

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

  ```json Response theme={null}
  {
    "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "name": "European Storefront",
    "currency": "EUR",
    "active": true,
    "created_at": "2024-06-15T10:00:00Z",
    "updated_at": "2024-06-15T10:00:00Z"
  }
  ```
</CodeGroup>

<Warning>
  Only users with the `Admin` or `Editor` role can create channels. A `403 Forbidden` response is returned for all other roles.
</Warning>