Skip to main content
The Channels API allows you to retrieve information about sales channels and integrations connected to a Square merchant account. Channels represent different ways merchants can sell, such as through locations, online sites, or third-party integrations.

​
Overview

The Channels client provides methods to:
  • List channels with filtering options
  • Retrieve a specific channel by ID
  • Bulk retrieve multiple channels

​
Client Initialization

import (
    "context"
    "github.com/square/square-go-sdk/v3"
    "github.com/square/square-go-sdk/v3/core"
)

client := square.NewClient(
    &core.RequestOptions{
        Token: "YOUR_ACCESS_TOKEN",
    },
)

​
Methods

​
List Channels

Retrieves a list of channels with optional filtering by reference type, reference ID, and status.
channels/client.go
request := &square.ListChannelsRequest{
    ReferenceType: square.ReferenceTypeLocation.Ptr(),
    Status:        square.ChannelStatusActive.Ptr(),
    Cursor:        square.String("cursor_value"),
    Limit:         square.Int(50),
}

response, err := client.Channels.List(context.TODO(), request)
if err != nil {
    // Handle error
}

for _, channel := range response.Channels {
    fmt.Printf("Channel: %s (ID: %s)\n", *channel.Name, *channel.ID)
    fmt.Printf("Type: %s\n", *channel.Reference.Type)
    fmt.Printf("Status: %s\n", *channel.Status)
}

// Handle pagination
if response.Cursor != nil {
    // Use response.Cursor for the next page
}
​
reference_type
*ReferenceType
Type of reference associated with the channel. Filters results to channels associated with this reference type.
​
reference_id
*string
ID of reference associated with the channel. Filters results to channels associated with this specific reference ID.
​
status
*ChannelStatus
Status of channel. Filters results by channel status:
  • ACTIVE: Active channels
  • INACTIVE: Inactive channels
​
cursor
*string
Pagination cursor to fetch the next result set
​
limit
*int
Maximum number of results to return. When not provided, the returned results will be capped at 100 channels.
​
channels
[]*Channel
List of requested channels
​
cursor
string
The pagination cursor for the next page of results

​
Get Channel

Retrieves a single channel by its ID.
channels/client.go
request := &square.GetChannelsRequest{
    ChannelID: "CHANNEL_ID",
}

response, err := client.Channels.Get(context.TODO(), request)
if err != nil {
    // Handle error
}

channel := response.Channel
fmt.Printf("Channel Name: %s\n", *channel.Name)
fmt.Printf("Status: %s\n", *channel.Status)
fmt.Printf("Reference Type: %s\n", *channel.Reference.Type)
fmt.Printf("Reference ID: %s\n", *channel.Reference.ID)
​
channelID
string
required
The unique ID of the channel to retrieve
​
channel
Channel
The requested channel object

​
Bulk Retrieve Channels

Retrieves multiple channels by their IDs in a single request.
channels/client.go
request := &square.BulkRetrieveChannelsRequest{
    ChannelIDs: []string{
        "CHANNEL_ID_1",
        "CHANNEL_ID_2",
        "CHANNEL_ID_3",
    },
}

response, err := client.Channels.BulkRetrieveChannels(context.TODO(), request)
if err != nil {
    // Handle error
}

// Process the responses map
for channelID, channelResponse := range response.Responses {
    if channelResponse.Channel != nil {
        fmt.Printf("Channel %s: %s\n", channelID, *channelResponse.Channel.Name)
    } else if len(channelResponse.Errors) > 0 {
        fmt.Printf("Failed to retrieve channel %s\n", channelID)
    }
}
​
channel_ids
[]string
required
Array of channel IDs to retrieve
​
responses
map[string]*RetrieveChannelResponse
A map of channel IDs to channel responses. Each response contains either channel info (success) or error info (failure).

​
Response Types

​
Channel

Represents a sales channel or integration.
​
id
string
The channel’s unique ID
​
merchant_id
string
The unique ID of the merchant this channel belongs to
​
name
string
The name of the channel
​
version
int
The version number which is incremented each time an update is made to the channel
​
reference
Reference
Represents an entity the channel is associated with
​
status
ChannelStatus
Status of the channel:
  • ACTIVE: The channel is active
  • INACTIVE: The channel is inactive
​
created_at
string
The timestamp for when the channel was created, in RFC 3339 format
​
updated_at
string
The timestamp for when the channel was last updated, in RFC 3339 format

​
ReferenceType

The type of platform concept a channel can represent:
  • UNKNOWN_TYPE: Unknown or unspecified type
  • LOCATION: A physical location
  • FIRST_PARTY_INTEGRATION: A Square first-party integration
  • OAUTH_APPLICATION: An OAuth application
  • ONLINE_SITE: A Square Online site
  • ONLINE_CHECKOUT: Square Online Checkout
  • INVOICE: Square Invoices
  • GIFT_CARD: Square Gift Cards
  • GIFT_CARD_MARKETPLACE: Gift Card Marketplace
  • RECURRING_SUBSCRIPTION: Subscriptions
  • ONLINE_BOOKING_FLOW: Square Appointments online booking
  • SQUARE_ASSISTANT: Square Assistant
  • CASH_LOCAL: Cash transactions
  • POINT_OF_SALE: Square Point of Sale
  • KIOSK: Kiosk devices

​
Use Cases

​
List All Active Location Channels

request := &square.ListChannelsRequest{
    ReferenceType: square.ReferenceTypeLocation.Ptr(),
    Status:        square.ChannelStatusActive.Ptr(),
    Limit:         square.Int(100),
}

response, err := client.Channels.List(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

fmt.Println("Active Location Channels:")
for _, channel := range response.Channels {
    fmt.Printf("- %s (Location ID: %s)\n", *channel.Name, *channel.Reference.ID)
}

​
Get Channels for a Specific Location

locationID := "LOCATION_ID"

request := &square.ListChannelsRequest{
    ReferenceType: square.ReferenceTypeLocation.Ptr(),
    ReferenceID:   square.String(locationID),
    Status:        square.ChannelStatusActive.Ptr(),
}

response, err := client.Channels.List(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Channels for location %s:\n", locationID)
for _, channel := range response.Channels {
    fmt.Printf("- %s (Created: %s)\n", *channel.Name, *channel.CreatedAt)
}

​
List All Online Channels

request := &square.ListChannelsRequest{
    ReferenceType: square.ReferenceTypeOnlineSite.Ptr(),
    Status:        square.ChannelStatusActive.Ptr(),
}

response, err := client.Channels.List(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

fmt.Println("Online Site Channels:")
for _, channel := range response.Channels {
    fmt.Printf("- %s (Site ID: %s)\n", *channel.Name, *channel.Reference.ID)
}

​
Retrieve Multiple Channels Efficiently

// Collect channel IDs from various sources
channelIDs := []string{"CHANNEL_1", "CHANNEL_2", "CHANNEL_3"}

// Bulk retrieve all channels in one request
request := &square.BulkRetrieveChannelsRequest{
    ChannelIDs: channelIDs,
}

response, err := client.Channels.BulkRetrieveChannels(context.TODO(), request)
if err != nil {
    log.Fatal(err)
}

// Process results
for id, channelResponse := range response.Responses {
    if channelResponse.Channel != nil {
        fmt.Printf("✓ %s: %s\n", id, *channelResponse.Channel.Name)
    } else {
        fmt.Printf("✗ %s: Failed to retrieve\n", id)
    }
}

​
Paginate Through All Channels

var allChannels []*square.Channel
var cursor *string

for {
    request := &square.ListChannelsRequest{
        Limit:  square.Int(100),
        Cursor: cursor,
    }
    
    response, err := client.Channels.List(context.TODO(), request)
    if err != nil {
        log.Fatal(err)
    }
    
    allChannels = append(allChannels, response.Channels...)
    
    // Check if there are more pages
    if response.Cursor == nil || *response.Cursor == "" {
        break
    }
    cursor = response.Cursor
}

fmt.Printf("Total channels retrieved: %d\n", len(allChannels))

​
Error Handling

response, err := client.Channels.Get(context.TODO(), request)
if err != nil {
    // Check for API errors
    if response != nil && len(response.Errors) > 0 {
        for _, e := range response.Errors {
            fmt.Printf("Error: %s - %s\n", e.Category, e.Detail)
        }
    }
    return err
}

Build docs developers (and LLMs) love

Get started for freeTalk to us