Channels

A channel is a distribution point where products are sold — an online store, wholesale portal, marketplace, or any other sales surface. Channels control checkout configuration (payment terms, minimum order amounts, PO requirements) and inventory allocation strategy per distribution point.

The channels extension must be enabled to create channels. The first channel created is automatically set as the default. Products are visible on all channels by default — use the product channel visibility endpoints to restrict availability.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
`GET`	`/v1/channels`	Secret	List channels
`POST`	`/v1/channels`	Secret	Create a channel
`GET`	`/v1/channels/{slug}`	Secret	Get a channel
`PATCH`	`/v1/channels/{slug}`	Secret	Update a channel
`DELETE`	`/v1/channels/{slug}`	Secret	Archive a channel
`PUT`	`/v1/channels/{slug}/default`	Secret	Set as default channel
`GET`	`/v1/products/{id}/channels`	Secret	Get product channels
`PUT`	`/v1/products/{id}/channels`	Secret	Set product channels
`PUT`	`/v1/collections/{id}/channels`	Secret	Set collection channels

List channels

GET /v1/channels

Returns a paginated list of channels. Archived channels are excluded unless ?status=archived is passed.

Query parameters

Parameter	Type	Default	Description
`limit`	integer	`20`	Results per page (1-100)
`cursor`	string	-	Pagination cursor from a previous response
`sort`	string	`created_at`	Sort field: `created_at`, `updated_at`, `label`
`order`	string	`desc`	Sort direction: `asc`, `desc`
`status`	string	-	Filter by status: `active`, `paused`, `archived`
`fields`	string	-	Comma-separated list of fields to include (sparse fieldsets)

Request

curl "https://api.hydrajs.dev/v1/channels" \
  -H "Authorization: Bearer sk_YOUR_KEY"

Response `200`

{
  "data": [
    {
      "id": "chan_abc123def456ghi789",
      "slug": "online-store",
      "label": "Online Store",
      "is_default": true,
      "status": "active",
      "location_ids": [],
      "allocation_strategy": "priority",
      "checkout_config": {},
      "created_at": "2026-08-28T12:00:00.000Z",
      "updated_at": "2026-08-28T12:00:00.000Z"
    },
    {
      "id": "chan_xyz789abc456def123",
      "slug": "wholesale",
      "label": "Wholesale Portal",
      "is_default": false,
      "status": "active",
      "location_ids": ["loc_abc123def456ghi789"],
      "allocation_strategy": "highest_stock",
      "checkout_config": {
        "payment_terms": "Net 30",
        "min_order": 50000,
        "po_required": true
      },
      "created_at": "2026-09-01T10:00:00.000Z",
      "updated_at": "2026-09-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "cursor": null,
    "has_more": false,
    "total": 2
  }
}

ℹPagination

All list endpoints use cursor-based pagination. Pass the cursor value from the response to fetch the next page.

Create a channel

POST /v1/channels

Creates a new sales channel. The slug is auto-generated from the label if not provided. The first channel created for a store is automatically set as the default.

Request body

Field	Type	Required	Description
`label`	string	Yes	Display name (1-255 chars)
`slug`	string	No	URL-friendly slug (max 100 chars). Auto-generated from label if omitted
`allocation_strategy`	string	No	`priority` or `highest_stock` (default `priority`)
`location_ids`	array	No	Array of location IDs to associate
`checkout_config`	object	No	Checkout rules (see below)

Checkout config object

Field	Type	Description
`payment_terms`	string	Payment terms text, e.g. “Net 30” (max 50 chars)
`min_order`	integer	Minimum order amount in cents (e.g. 50000 = $500)
`po_required`	boolean	Whether a purchase order number is required

Request

curl -X POST https://api.hydrajs.dev/v1/channels \
  -H "Authorization: Bearer sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Wholesale Portal",
    "allocation_strategy": "highest_stock",
    "checkout_config": {
      "payment_terms": "Net 30",
      "min_order": 50000,
      "po_required": true
    }
  }'

Response `201`

{
  "data": {
    "id": "chan_xyz789abc456def123",
    "slug": "wholesale-portal",
    "label": "Wholesale Portal",
    "is_default": false,
    "status": "active",
    "location_ids": [],
    "allocation_strategy": "highest_stock",
    "checkout_config": {
      "payment_terms": "Net 30",
      "min_order": 50000,
      "po_required": true
    },
    "created_at": "2026-09-01T10:00:00.000Z",
    "updated_at": "2026-09-01T10:00:00.000Z"
  }
}

Get a channel

GET /v1/channels/{slug}

Returns a single channel by its slug.

Request

curl "https://api.hydrajs.dev/v1/channels/wholesale-portal" \
  -H "Authorization: Bearer sk_YOUR_KEY"

Response `200`

{
  "data": {
    "id": "chan_xyz789abc456def123",
    "slug": "wholesale-portal",
    "label": "Wholesale Portal",
    "is_default": false,
    "status": "active",
    "location_ids": ["loc_abc123def456ghi789"],
    "allocation_strategy": "highest_stock",
    "checkout_config": {
      "payment_terms": "Net 30",
      "min_order": 50000,
      "po_required": true
    },
    "created_at": "2026-09-01T10:00:00.000Z",
    "updated_at": "2026-09-01T10:00:00.000Z"
  }
}

Update a channel

PATCH /v1/channels/{slug}

Partially updates a channel. All fields are optional — send only what changed. Cannot change is_default via PATCH; use the set default endpoint instead.

Request body

Field	Type	Description
`label`	string	Display name (1-255 chars)
`slug`	string	URL-friendly slug (max 100 chars)
`status`	string	`active` or `paused`. Cannot pause the default channel
`allocation_strategy`	string	`priority` or `highest_stock`
`location_ids`	array	Array of location IDs
`checkout_config`	object	Checkout rules. Set individual fields to `null` to clear

Request

curl -X PATCH https://api.hydrajs.dev/v1/channels/wholesale-portal \
  -H "Authorization: Bearer sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Wholesale B2B",
    "checkout_config": {
      "min_order": 100000,
      "payment_terms": null
    }
  }'

Response `200`

Returns the full updated channel object (same shape as Get a channel).

Archive a channel

DELETE /v1/channels/{slug}

Archives a channel. The slug is mutated to free the unique constraint so a new channel can reuse it. Cannot archive the default channel.

Request

curl -X DELETE https://api.hydrajs.dev/v1/channels/wholesale-portal \
  -H "Authorization: Bearer sk_YOUR_KEY"

Response `204`

Empty body.

⚠Default channel protection

The default channel cannot be archived. Set a different channel as default first, then archive the old one.

Set default channel

PUT /v1/channels/{slug}/default

Sets the specified channel as the default. The previous default is unset in the same transaction. Cannot set a paused or archived channel as default.

Request

curl -X PUT https://api.hydrajs.dev/v1/channels/wholesale-portal/default \
  -H "Authorization: Bearer sk_YOUR_KEY"

Response `200`

{
  "data": {
    "id": "chan_xyz789abc456def123",
    "slug": "wholesale-portal",
    "label": "Wholesale Portal",
    "is_default": true,
    "status": "active",
    "location_ids": [],
    "allocation_strategy": "highest_stock",
    "checkout_config": {
      "payment_terms": "Net 30",
      "min_order": 50000,
      "po_required": true
    },
    "created_at": "2026-09-01T10:00:00.000Z",
    "updated_at": "2026-10-01T14:30:00.000Z"
  }
}

Product channel visibility

By default, products are visible on all channels. Use these endpoints to restrict a product to specific channels.

Get product channels

GET /v1/products/{id}/channels

Returns the channel visibility mode and list of channel slugs for a product.

curl "https://api.hydrajs.dev/v1/products/prod_abc123/channels" \
  -H "Authorization: Bearer sk_YOUR_KEY"

Response `200`

{
  "data": {
    "mode": "specific",
    "channels": ["online-store", "wholesale-portal"]
  }
}

The mode field is "all" when the product is visible everywhere, or "specific" when restricted to listed channels.

Set product channels

PUT /v1/products/{id}/channels

Sets the channel visibility for a product. Pass an empty array to make the product visible on all channels.

curl -X PUT https://api.hydrajs.dev/v1/products/prod_abc123/channels \
  -H "Authorization: Bearer sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": ["online-store", "wholesale-portal"]
  }'

Response `200`

{
  "data": {
    "mode": "specific",
    "channels": ["online-store", "wholesale-portal"]
  }
}

Webhooks

Channel changes fire the following webhook events:

Event	Trigger
`channel.created`	A channel is created
`channel.updated`	A channel is updated or default is changed
`channel.archived`	A channel is archived

See Webhooks for subscription setup.

The channel object

Field	Type	Description
`id`	string	Unique ID (prefix: `chan_`)
`slug`	string	URL-friendly slug, unique per project
`label`	string	Human-readable display name
`is_default`	boolean	Whether this is the default channel
`status`	string	`active`, `paused`, or `archived`
`location_ids`	array	IDs of associated locations
`allocation_strategy`	string	`priority` (respects location order) or `highest_stock` (picks location with most units)
`checkout_config`	object	Checkout rules for this channel
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Checkout config fields

Field	Type	Description
`payment_terms`	string \| null	Payment terms text (e.g. “Net 30”)
`min_order`	integer \| null	Minimum order amount in cents
`po_required`	boolean \| null	Whether a purchase order number is required

Channels

Endpoints

List channels

Query parameters

Request

Response 200

Create a channel

Request body

Checkout config object

Request

Response 201

Get a channel

Request

Response 200

Update a channel

Request body

Request

Response 200

Archive a channel

Request

Response 204

Set default channel

Request

Response 200

Product channel visibility

Get product channels

Response 200

Set product channels

Response 200

Webhooks

The channel object

Checkout config fields

Response `200`

Response `201`

Response `200`

Response `200`

Response `204`

Response `200`

Response `200`

Response `200`