# How to list sales channels (https://developer.godaddy.com/en/docs/api-users/commerce/set-up-a-store/channel)

***

title: How to list sales channels
description: Query the sales channels registered to a store — online, retail, mobile, and more.
agentNotes:
permissions: \[]
scopes: \["commerce.channel:read"]
idempotent: true
destructive: false
failureRecovery: "Safe to retry on any error. Channel reads are idempotent."
related:
apis:

* title: "Channel API reference"
  href: "/docs/references/rest/channels/channel"
  guides:
* title: "Manage a store"
  href: "/docs/api-users/commerce/set-up-a-store"
  concepts:
* title: "Commerce core concepts"
  href: "/docs/api-users/commerce/concepts"
* title: "Authentication"
  href: "/docs/api-users/auth"
* title: "Rate limits"
  href: "/docs/api-users/rate-limits"

***

## Overview

Channels represent the surfaces customers can buy from (like an online store, a point-of-sale terminal, a mobile app, or a third-party marketplace). This page covers how to list and read sales channels for a store.

## Prerequisites

The following prerequisites are required before you can list sales channels for a store:

* a GoDaddy account with an active commerce store
* a [Personal Access Token (PAT)](https://developer.godaddy.com/docs/api-users/auth) with the `commerce.channel:read` scope
* your `storeId`

  Go to [Your stores](https://developer.godaddy.com/docs/api-users/commerce#your-stores) to find your store ID.

## List channels

`GET /v1/commerce/channels` retrieves sales channels matching the supplied filter. Include at least one of these query parameters — `registeredStores.storeId` (filter by store) or `externalChannelId` (filter by the channel's external ID). A request with neither returns `400 INVALID_REQUEST`.

The following procedure lists channels registered to a specific store using `registeredStores.storeId`:

1. Retrieve a list of channels registered to a specific store:

   ```bash tab="curl"
   curl -s "https://api.godaddy.com/v1/commerce/channels?registeredStores.storeId=${STORE_ID}" \
     -H "Authorization: Bearer $GODADDY_PAT"
   ```

   ```js tab="Node"
   const token = process.env.GODADDY_PAT;
   const storeId = process.env.STORE_ID;

   const res = await fetch(
     `https://api.godaddy.com/v1/commerce/channels?registeredStores.storeId=${storeId}`,
     { headers: { Authorization: `Bearer ${token}` } }
   );
   const channels = await res.json();
   console.log(channels);
   ```

   ```python tab="Python"
   import os, requests

   token = os.environ["GODADDY_PAT"]
   store_id = os.environ["STORE_ID"]

   res = requests.get(
       "https://api.godaddy.com/v1/commerce/channels",
       params={"registeredStores.storeId": store_id},
       headers={"Authorization": f"Bearer {token}"},
   )
   res.raise_for_status()
   for channel in res.json():
       print(channel["id"], channel["name"], channel["type"])
   ```

   ```go tab="Go"
   package main

   import (
       "encoding/json"
       "fmt"
       "net/http"
       "os"
   )

   func main() {
       token := os.Getenv("GODADDY_PAT")
       storeId := os.Getenv("STORE_ID")

       url := fmt.Sprintf("https://api.godaddy.com/v1/commerce/channels?registeredStores.storeId=%s", storeId)
       req, _ := http.NewRequest("GET", url, nil)
       req.Header.Set("Authorization", "Bearer "+token)

       res, err := http.DefaultClient.Do(req)
       if err != nil { panic(err) }
       defer res.Body.Close()

       var channels []map[string]any
       json.NewDecoder(res.Body).Decode(&channels)
       fmt.Println(channels)
   }
   ```

2. Review the response array of channel objects:

   ```json
   [
     {
       "id": "<ONLINE_CHANNEL_ID>",
       "name": "<ONLINE_CHANNEL_DISPLAY_NAME>",
       "type": "<CHANNEL_TYPE>",
       "status": "<LIFECYCLE_STATUS>",
       "storeId": "<STORE_UUID>",
       "createdAt": "<ISO8601_CREATED_TIMESTAMP>",
       "updatedAt": "<ISO8601_UPDATED_TIMESTAMP>"
     },
     {
       "id": "<RETAIL_CHANNEL_ID>",
       "name": "<RETAIL_CHANNEL_DISPLAY_NAME>",
       "type": "<CHANNEL_TYPE>",
       "status": "<LIFECYCLE_STATUS>",
       "storeId": "<STORE_UUID>",
       "createdAt": "<ISO8601_CREATED_TIMESTAMP>",
       "updatedAt": "<ISO8601_UPDATED_TIMESTAMP>"
     }
   ]
   ```

## Get channel by ID

`GET /v1/commerce/channels/{channelId}` retrieves a specific sales channel. PAT callers with store-level `commerce.channel:read` often receive `401` on this route because the service requires a per-resource FGA relation. List channels for the store and filter instead:

```bash
curl -s "https://api.godaddy.com/v1/commerce/channels?registeredStores.storeId=${STORE_ID}" \
  -H "Authorization: Bearer $GODADDY_PAT" \
  | jq '.items[] | select(.channelId == "<SALES_CHANNEL_ID>")'
```

That returns the full channel object. The get-by-id examples below are the documented route; use the list workaround when get-by-id returns `401`.

The following procedure reads a single channel by ID.

* Retrieve a single channel by its `id`:

  ```bash tab="curl"
  CHANNEL_ID="<SALES_CHANNEL_ID>"

  curl -s "https://api.godaddy.com/v1/commerce/channels/${CHANNEL_ID}" \
    -H "Authorization: Bearer $GODADDY_PAT"
  ```

  ```js tab="Node"
  const token = process.env.GODADDY_PAT;
  const channelId = "<SALES_CHANNEL_ID>";

  const res = await fetch(
    `https://api.godaddy.com/v1/commerce/channels/${channelId}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );
  const channel = await res.json();
  console.log(channel);
  ```

  ```python tab="Python"
  import os, requests

  token = os.environ["GODADDY_PAT"]
  channel_id = "<SALES_CHANNEL_ID>"

  res = requests.get(
      f"https://api.godaddy.com/v1/commerce/channels/{channel_id}",
      headers={"Authorization": f"Bearer {token}"},
  )
  res.raise_for_status()
  print(res.json())
  ```

  ```go tab="Go"
  package main

  import (
      "encoding/json"
      "fmt"
      "net/http"
      "os"
  )

  func main() {
      token := os.Getenv("GODADDY_PAT")
      channelId := "<SALES_CHANNEL_ID>"

      url := fmt.Sprintf("https://api.godaddy.com/v1/commerce/channels/%s", channelId)
      req, _ := http.NewRequest("GET", url, nil)
      req.Header.Set("Authorization", "Bearer "+token)

      res, err := http.DefaultClient.Do(req)
      if err != nil { panic(err) }
      defer res.Body.Close()

      var channel map[string]any
      json.NewDecoder(res.Body).Decode(&channel)
      fmt.Println(channel)
  }
  ```

## Channel types

Each channel has a `type` from the Channels API enum. Use `subType` for product-specific detail (for example, a marketplace provider or website product); `subType` is set when the channel is registered and cannot be changed.

| Type          | Description                                                                                                    |
| ------------- | -------------------------------------------------------------------------------------------------------------- |
| `RETAIL`      | Physical retail location where merchant and customer transact in person (stores, pop-ups, food trucks)         |
| `ONLINE`      | Web or online storefront sales                                                                                 |
| `MOBILE`      | Mobile app sales surface                                                                                       |
| `MARKETPLACE` | External marketplace (for example Amazon or eBay)                                                              |
| `SOCIAL`      | Social commerce (for example Facebook or Instagram)                                                            |
| `DEFAULT`     | Platform default channel for the store; only one `DEFAULT` channel per store (often used for default payments) |

## Common errors

| Status | Most likely cause                                                                                  |
| ------ | -------------------------------------------------------------------------------------------------- |
| `400`  | Neither `registeredStores.storeId` nor `externalChannelId` was supplied. At least one is required. |
| `401`  | PAT is missing or expired. Go to [Authentication](https://developer.godaddy.com/docs/api-users/auth) to generate a new token.   |
| `403`  | Token doesn't include the `commerce.channel:read` scope.                                           |
| `404`  | Channel ID doesn't exist or isn't accessible with the provided token.                              |
| `429`  | Rate limit exceeded. Honor the `Retry-After` header before retrying.                               |