Channels API

Applies to: Channels API

Learn how to use a Square API to retrieve channel information for a Square seller.

The Square Channels API allows you to manage and retrieve information about channels associated with a seller's account. A channel represents the link between a seller and the platforms or services where they conduct business — the medium through which buyers and sellers interact. Conceptually, a channel serves as an abstraction or interface that can be implemented by various objects or entities within the Square ecosystem.

A channel can be one of the following classes:

• Sales channel - The mechanism that created an Order, order line items, or both.
• Marketing channel - The mechanism that sourced the traffic that resulted in an order. This is generally limited to channels (internal or external) that directly pull product or service listings from the Square platform.
• Fulfillment channel - The mechanism that fulfilled the Order.

A Channel object can be associated with various platform concepts through its reference field. The Reference object includes:

• type - The type of platform concept (required).
• id - The ID of the referenced entity (required).

The Channels API provides the following endpoints for retrieving channel information:

• BulkRetrieveChannels - Looks up multiple channels in a single request.
• ListChannels - Retrieves a list of all channels with optional filtering.
• RetrieveChannel - Retrieves detailed information about a specific channel.

The Channels API gives your application the ability to report on the marketing, sales, and fulfillment channels available to a seller and which products and services are available through each channel.

Integrating the Channels API with the Catalog and Location APIs allows for many use cases that a seller limit the visibility of catalog objects to channels such as a seller's locations or the point of sale used to make a sale.

The Channels API is essential for understanding how catalog items are distributed across a seller’s sales channels. When used alongside a catalog item variation’s channels_integrations properties, it enables applications to determine exactly where specific products can be sold or services can be offered.

For example, consider a coffee shop that sells ceramic mugs. The Channels API lists all available sales channels (from physical store locations to online shops), while the catalog data identifies which mugs are available through each channel. Together, they allow applications to accurately display product availability, whether an item is limited to certain store locations, available at all POS systems, or listed online.

Beyond catalog management, the API also helps applications discover enabled Square services (like gift cards or invoicing) and identify authorized third-party integrations. This allows applications to dynamically adapt their features to match the seller's capabilities and channel configuration.

Unlike other Catalog objects, CatalogCategory objects cannot be directly assigned to locations. Instead, they use a channel-based visibility system to determine where menus appear across a seller's locations.

• Menu Categories: CatalogCategory objects with category_type set to MENU_CATEGORY form the structure of menus created in the Square Dashboard
• Channels: Represent different distribution points for catalog content, including physical locations
• Channel References: Link channels to specific entities like locations

When a seller creates and manages menus in the Square Dashboard:

1. They define menu categories (CatalogCategory objects)
2. They assign these categories to specific locations through the Dashboard interface
3. Behind the scenes, Square uses channels to manage this visibility

To find which menu categories are visible at a specific location using the Catalog API:

First, retrieve all channels for the seller. Look for channels where reference.type equals LOCATION - these represent the seller's physical locations.

Example Response:

{
  "channels": [
    {
      "id": "CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
      "merchant_id": "25PR2SBM8PV5D",
      "name": "FlamingRed",
      "version": 1,
      "reference": {
        "type": "LOCATION",
        "id": "E78VDDVFW1EYX"    // This is the Location ID
      },
      "status": "ACTIVE",
      "created_at": "2023-04-26T13:10:24.808Z",
      "updated_at": "2023-04-26T13:10:24.808Z"
    },
    {
      "id": "CH_4s6dFPG7nd0Axgdcu8NXQqPO54qnOXkyQRkiBQlQuYC",
      "merchant_id": "25PR2SBM8PV5D",
      "name": "Seed Data test",
      "reference": {
        "type": "LOCATION",
        "id": "LFF3HK0DN6A61"
      },
      "status": "ACTIVE"
    },
    {
      "id": "CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o",
      "merchant_id": "25PR2SBM8PV5D",
      "name": "Online store",
      "reference": {
        "type": "LOCATION",
        "id": "LRAXEJYQZ0JED"
      },
      "status": "ACTIVE"
    }
  ]
}

From the channels response, create a mapping:

When you retrieve a menu category, check its channels array to see which locations can display it.

Example: Breakfast Menu Category

{
  "object": {
    "type": "CATEGORY",
    "id": "3H3ADZMYJU6U27JYO2PZFANQ",
    "updated_at": "2025-08-06T07:21:55.923Z",
    "created_at": "2025-06-02T18:24:46.958Z",
    "version": 1754464915923,
    "is_deleted": false,
    "present_at_all_locations": true,
    "category_data": {
      "name": "Breakfast menu",
      "category_type": "MENU_CATEGORY",
      "parent_category": {
        "ordinal": 137439154960
      },
      "is_top_level": true,
      "channels": [
        "CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC"  // FlamingRed channel
      ],
      "online_visibility": false
    }
  }
}

This breakfast menu category includes the channel ID CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC, which corresponds to the "FlamingRed" location (E78VDDVFW1EYX).

To retrieve a list of all channels, use the ListChannels endpoint. This endpoint supports filtering and pagination. Filters are useful when a seller has many channels of various types. You can filter the channels list by:

• reference_type - Filter by the type of reference associated with the channel.
• status - Filter by channel status.

The two filter types can be combined into an AND query but you cannot request multiple values for a given filter. For example, you can request channels of reference_type == LOCATION and status == ACTIVE but you cannot request channels of (reference_type == LOCATION OR reference_type == KIOSK) and status == ACTIVE.

Use the BulkRetrieveChannels endpoint when you need to retrieve information about multiple specific channels at once. This is more efficient than making individual requests for each channel.

The source for the channel ID list might be the results of a SearchCatalogObjects query that returns a long list of catalog objects. Each object that has channel ID information can be parsed to get the referenced ID and then added to the BulkRetrieveChannels query. An application might also cache the most frequently referenced channel IDs and then run the BulkRetrieveChannels request to get the current state of these channels.

Important notes:

• You can request up to 100 channels in a single request.
• The response includes a map of channel IDs to their corresponding channel information.
• If any channels cannot be retrieved, the response includes error details for those specific channels.

When you need information about a specific channel, use the RetrieveChannel endpoint.

All Channels API endpoints:

• Support OAuth 2.0 access tokens.
• Require CHANNELS_READ permission for OAuth 2.0 authentication.

Common error codes across all endpoints include:

• UNAUTHORIZED - Invalid authentication credentials.
• FORBIDDEN - Insufficient permissions.
• MISSING_REQUIRED_PARAMETER - Required parameters are missing from the request.

The RetrieveChannel endpoint might also return:

• NOT_FOUND - The requested channel ID doesn't exist.

All endpoints are currently in Beta status except where noted. The current API version for these endpoints is 2025-10-16.