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.
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.
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.
This example asks for a list of all active channel locations:
List channels
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.
In this example, the application caches the channel IDs for a seller's locations and the third-party applications that they're using. With one request, the application gets the channel information for these locations and applications.
Bulk retrieve 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.
This example requests a channel whose ID is CH_KH0VQTd9HzLmOWRGrF16agtdnoQ9JrkS4gEd5PlQuYC.
Retrieve channel
All Channels API endpoints:
- Support OAuth 2.0 access tokens.
- Require
CHANNELS_READpermission 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.