List Coupon Codes

GET

https://api.bigcommerce.com/stores/:store_hash/v3/promotions/:promotion_id/codes

GET

/stores/:store_hash/v3/promotions/:promotion_id/codes

curl -G https://api.bigcommerce.com/stores/store_hash/v3/promotions/promotion_id/codes \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>" \
     -d code=TEST_COUPON \
     -d valid_from:min=1756684800 \
     -d valid_until:max=1759276800

200example-1

{
  "data": [
    {
      "id": 1,
      "code": "TEST_COUPON",
      "current_uses": 0,
      "created": "2019-01-20T22:00:00+00:00",
      "max_uses": 10,
      "max_uses_per_customer": 5,
      "schedule": {
        "valid_from": "2026-09-01T00:00:00+00:00",
        "valid_until": "2026-09-30T23:59:59+00:00"
      }
    }
  ],
  "meta": {
    "cursor_pagination": {
      "count": 1,
      "per_page": 50,
      "links": {
        "next": "?limit=5&after=eyJpZCI6IjIzNzU1NyJ9"
      },
      "start_cursor": "eyJpZCI6IjIzNzU1NyJ9",
      "end_cursor": "eyJpZCI6IjIzNzU1MyJ9"
    },
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 50,
      "current_page": 1,
      "total_pages": 1,
      "links": {
        "current": "?page=1&limit=50"
      }
    }
  }
}

Get codes for a particular promotion.

Note: The default rate limit for this endpoint is 10 concurrent requests.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Marketing	modify	`store_v2_marketing`
Marketing	read-only	`store_v2_marketing_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see API Accounts and OAuth Scopes.

Path parameters

promotion_idstringRequired

The ID of the associated promotion.

store_hashstringRequired

Permanent ID of the BigCommerce store.

Query parameters

beforestringOptional

A cursor that can be used for backwards pagination. Will fetch results before the position corresponding to the cursor. Cannot be used with the 'page' query parameter. Cannot be used with the 'after' query parameter.

afterstringOptional

A cursor that can be used for forwards pagination. Will fetch results after the position corresponding to the cursor. Cannot be used with the 'page' query parameter. Cannot be used with the 'before' query parameter.

pageintegerOptional>=1Deprecated

Query parameter that specifies the page number in a paginated list of resources. This field is deprecated and the 'before' and 'after' cursor parameters should be used instead.

limitintegerOptional1-250

Query parameter that limits the number of items displayed per page in a paginated list of resources. When none is specified a default value of 50 is used.

codestringOptional

Filter items by code.

valid_from:minintegerOptional>=1

Return only codes with a custom valid_from on or after this value. The value is a positive integer Unix timestamp.

valid_until:maxintegerOptional>=1

Return only codes with a custom valid_until on or before this value. The value is a positive integer Unix timestamp.

Response

A list of coupon codes.

datalist of objectsOptional

metaobjectOptional

Contains data about paginating the response via cursors. If no pagination details are specified, then both properties will be present. When a ‘before’ or ‘after’ cursor is provided, only the ‘cursor_pagination’ property will be present. When a ‘page’ parameter is provided, only the offset based ‘pagination’ property will be present.