Skip to main content

Channel API guide

Getting Channel Details​

Use the channel query to get channel details.

The channel query requires a channel ID or channel slug.

Available fields:

  • id: Channel object ID
  • slug: When using channel-dependent queries, the slug is used to select the right channel (for example, when requesting product details).
  • name: Channel name
  • isActive: Flag signaling that the channel is available for shop customers.
  • currencyCode: Currency code used by the channel.
  • hasOrders: Returns true when there are already created orders using that channel. If that's the only channel using this currency, you won't be able to remove it.
  • defaultCountry: Default country for the channel. The default country is used in checkout to determine stock quantities or calculate taxes when the country is not explicitly provided, either as a query parameter or through a shipping address.
  • warehouses: Warehouses that are available in the given channel.
  • countries: List of shippable countries for the channel.
  • availableShippingMethodsPerCountry: Shipping methods that are available for the channel.
  • stockSettings: Contains all stock-related settings, e.g., the allocation strategy for the channel.
  • orderSettings: Channel-specific order settings.
  • checkoutSettings: Controls automatic checkout completion and error handling.
  • paymentSettings: Defines the default transaction flow strategy: AUTHORIZATION or CHARGE.
query channel($slug: String) {
  channel(slug: $slug) {
    id
    slug
    name
    isActive
    currencyCode
    hasOrders
    defaultCountry {
      code
      country
    }
    warehouses {
      slug
    }
    countries {
      code
      country
    }
    availableShippingMethodsPerCountry {
      countryCode
      shippingMethods {
        id
        name
      }
    }
    stockSettings {
      allocationStrategy
    }
    orderSettings {
      allowUnpaidOrders
    }
  }
}

Permissions​

Listing channels is allowed only for users with the active isStaff flag.

You need the MANAGE_CHANNELS permission to create, edit, and remove channels. Changing ChannelListing does not require additional permissions. For example, changing product availability requires only the MANAGE_PRODUCTS permission.

Objects with customized per-channel visibility are restricted by channel permissions. If a user with restricted channel access fetches per-channel objects, only objects from accessible channels are returned. Read more about channel permissions in Permissions.

Creating a New Channel​

You can create a new channel using the channelCreate mutation. During channel creation, you can configure not only slug or currency but also stock, order, checkout, payment behaviors, and assign warehouses and shipping zones.

mutation channelCreate($input: ChannelCreateInput!) {
  channelCreate(input: $input) {
    channel {
      id
      isActive
      name
      slug
      currencyCode
      defaultCountry {
        code
        country
      }
      stockSettings {
        allocationStrategy
      }
      orderSettings {
        automaticallyConfirmAllNewOrders
      }
      checkoutSettings {
        automaticallyCompleteFullyPaidCheckouts
      }
      paymentSettings {
        defaultTransactionFlowStrategy
      }
      warehouses {
        name
      }
    }
    errors {
      code
      field
      message
    }
  }
}

Channel Settings​

Each channel can have an independent configuration for orders, checkout, stock, and payments. These settings are available under the fields: orderSettings, checkoutSettings, stockSettings, and paymentSettings.

Stock Settings​

Channel-level stock settings control how inventory is allocated to orders.

  • allocationStrategy: Determines which warehouse is used first when reserving stock.
    • PRIORITIZE_HIGH_STOCK: Prefer warehouses with higher on-hand stock.
    • PRIORITIZE_SORTING_ORDER: Follow the warehouse order defined for the channel (default).

Read more about stock allocation.

Reorder Warehouses Within Channels​

You can change the warehouse order using the channelReorderWarehouses mutation.

The sortOrder in the moves input represents the new relative position of the item. When 1 is provided, the item is moved one position forward; when -1, one position backward.

Assume we have a channel with three warehouses in the following order:

{
  "data": {
    "channel": {
      "id": "Q2hhbm5lbDox",
      "warehouses": [
        {
          "id": "V2FyZWhvdXNlOjU1NTZiOWI0LTc1ZTItNGI3YS1hZWM1LTQxOTY4NDA2OGE4OA==",
          "slug": "europe"
        },
        {
          "id": "V2FyZWhvdXNlOjQwZWY1MTQwLWQ5OTYtNDVlNy04NzUzLTlkZThkMTdhMjg1Yw==",
          "slug": "oceania"
        },
        {
          "id": "V2FyZWhvdXNlOjY4M2FkMzZhLTRmNjktNDI2ZS1iYzUyLTMyZGJiZTQ2NjUyZA==",
          "slug": "americas"
        }
      ]
    }
  }
}

To move the americas warehouse to the first position and the europe warehouse to the third position, run the following mutation:

mutation channelReorderWarehouses($channelId: ID!, $moves: [ReorderInput!]!) {
  channelReorderWarehouses(channelId: $channelId, moves: $moves) {
    channel {
      id
      warehouses {
        id
        slug
      }
    }
    errors {
      field
      code
      message
      warehouses
    }
  }
}

Order Settings​

Channel-level order settings influence how orders behave after being placed (post-checkout or created from draft). You can define auto-confirmation, gift card auto-fulfillment, order expiration, and whether unpaid orders are allowed.

Read more about order settings.

Checkout Settings​

Channel-specific checkout behavior allows you to enable automatic completion of paid checkouts.

Read more about automatic checkout completion.

Payment Settings​

Channel-level payment settings influence how the payment flow is handled. Use defaultTransactionFlowStrategy to set the default flow.

Read more about the transaction strategy.

Channel List​

Because some channels may be considered non-public (for example, a channel for business partners), non-staff users cannot use the channels query.

query {
  channels {
    name
  }
}

Managing Channels​

Activate or Deactivate a Channel​

To make a channel unavailable for customers, change its status to deactivated using the channelDeactivate mutation:

mutation channelDeactivate($id: ID!) {
  channelDeactivate(id: $id) {
    channel {
      name
      isActive
    }
    errors {
      message
    }
  }
}

To reverse the previous operation, use the channelActivate mutation:

mutation channelActivate($id: ID!) {
  channelActivate(id: $id) {
    channel {
      name
      isActive
    }
    errors {
      message
    }
  }
}

Update Channel​

Use the channelUpdate mutation to edit channel fields such as name, shipping zones or settings.

mutation ChannelUpdate($id: ID!, $input: ChannelUpdateInput!) {
  channelUpdate(id: $id, input: $input) {
    channel {
      id
      slug
      warehouses{
        name
      }
      orderSettings {
        automaticallyConfirmAllNewOrders
      }
      checkoutSettings {
        automaticallyCompleteFullyPaidCheckouts
      }
      paymentSettings {
        defaultTransactionFlowStrategy
      }
    }
    errors {
      field
      code
      message
    }
  }
}

Removing a Channel​

Channels can be removed only when:

  • There are no orders created in them.
  • If there are existing orders, it is required to provide the ID of a destination channel in ChannelDeleteInput using the field channelId. Its currency must be the same as the channel you are about to delete. All orders will be moved to this channel.

Use channelDelete to remove channel.

mutation channelDelete($id: ID!, $input: ChannelDeleteInput) {
  channelDelete(id: $id, input: $input) {
    errors {
      field
      code
      message
    }
    channel{
      name
    }
  }
}