Get Coupon Code

GET

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

GET

/stores/:store_hash/v3/promotions/codes

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

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 a coupon with a given coupon code.

Note: The default rate limit for this endpoint is 40 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

store_hashstringRequired

Permanent ID of the BigCommerce store.

Query parameters

codestringRequired

Filter items by code.

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.