> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # List Coupon Codes GET https://api.bigcommerce.com/stores/{store_hash}/v3/promotions/{promotion_id}/codes Get codes for a particular promotion. **Note:** The default rate limit for this endpoint is 10 concurrent requests. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/promotions/coupon-codes-bulk/get-promotion-codes ## Authentication - `X-Auth-Token` header (required) — ### 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](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts). For more about BigCommerce OAuth scopes, see [API Accounts and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes). ## Request ### Path parameters - `promotion_id` (string, required) — The ID of the associated promotion. - `store_hash` (string, required) — Permanent ID of the BigCommerce store. ### Query parameters - `before` (string, optional) — 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. - `after` (string, optional) — 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. - `page` (integer, optional, deprecated) — 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. - `limit` (integer, optional) — 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. - `code` (string, optional) — Filter items by `code`. - `valid_from:min` (integer, optional) — Return only codes with a custom `valid_from` on or after this value. The value is a positive integer Unix timestamp. - `valid_until:max` (integer, optional) — Return only codes with a custom `valid_until` on or before this value. The value is a positive integer Unix timestamp. ### Headers - `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. ## Response ### 200 A list of coupon codes. - `data` (list of CouponCode, optional) - `meta` (OptionalCursorCollectionMeta, optional) — 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. ## Types ### CouponCode A `CouponCode` object encapsulates attributes of a coupon code. - `id` (integer, required) — An auto-generated unique identifier for the coupon code. - `code` (string, required) — A unique code that can be used to manually apply a discount. Only letters, numbers, white spaces, underscores and hyphens are allowed. - `current_uses` (integer, required) — A read-only count of the times this coupon code has been used. - `created` (datetime, required) — The date and time when this coupon code was created. - `max_uses` (integer, optional) — The maximum number of times you can use this coupon code. The default value is 0, which represents unlimited uses. - `max_uses_per_customer` (integer, optional) — The maximum number of times a specific customer can use this coupon code. The default value is 0, which represents unlimited uses. - `schedule` (CouponCodeSchedule, optional, nullable) — The custom validity window of this coupon code. `null` when the code inherits the promotion's schedule. A code is custom-scheduled if and only if `schedule` is non-null. Note: the promotion object also has a field named `schedule`. That field controls on which days of the week the promotion is available, and has no relation to this field. ### OptionalCursorCollectionMeta 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. - `cursor_pagination` (CursorPagination, optional) — Contains data about paginating the response via cursors. - `pagination` (DeprecatedPagination, optional, deprecated) — Data about the response, including pagination and collection totals. This property has been deprecated and cursor_pagination should be used instead. ### CouponCodeSchedule A custom validity window for a coupon code, independent of (but fully contained within) the parent promotion's schedule. - `valid_from` (datetime, required) — The date and time from which the code can be redeemed (RFC3339 UTC). Must be within the promotion's schedule. - `valid_until` (datetime, required, nullable) — The date and time until which the code can be redeemed (RFC3339 UTC). Must be after `valid_from` and within the promotion's schedule. `null` means no end, and is only allowed if the parent promotion does not have an end date. Must not be `null` if the parent promotion has an end date. ### CursorPagination Contains data about paginating the response via cursors. - `count` (integer, required) — Total number of items in the result set. - `per_page` (integer, required) — The amount of items returned in the collection per page, controlled by the limit of items per page parameter. - `links` (CursorPaginationLinks, required) - `start_cursor` (string, optional) — The cursor to the first item in the result set. Can be used with the "before" query parameter to paginate backwards. This property is omitted when the result set is empty. - `end_cursor` (string, optional) — The cursor to the last item in the result set. Can be used with the "after" query parameter to paginate forwards. This property is omitted when the result set is empty. ### DeprecatedPagination Data about the response, including pagination and collection totals. This property has been deprecated and cursor_pagination should be used instead. - `total` (integer, optional) — Total number of items in the result set. - `count` (integer, optional) — Total number of items in the collection response. - `per_page` (integer, optional) — The amount of items returned in the collection per page, controlled by the limit of items per page parameter. - `current_page` (integer, optional) — The page you are currently on within the collection. - `total_pages` (integer, optional) — The total number of pages in the collection. - `links` (DeprecatedPaginationLinks, optional) — Pagination links for the previous and next parts of the whole collection. ### CursorPaginationLinks - `previous` (string, optional) — Link to the previous page returned in the response. This property is omitted when the result set is empty or on the first page. - `next` (string, optional) — Link to the next page returned in the response. This property is omitted when the result set is empty. ### DeprecatedPaginationLinks Pagination links for the previous and next parts of the whole collection. - `previous` (string, optional) — Link to the previous page returned in the response. - `current` (string, optional) — Link to the current page returned in the response. - `next` (string, optional) — Link to the next page returned in the response. ## Examples **Response** ```json { "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" } } } } ``` **SDK Code** ```python example-1 import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/promotions/promotion_id/codes" querystring = {"code":"TEST_COUPON","valid_from:min":"1756684800","valid_until:max":"1759276800"} headers = { "Accept": "application/json", "X-Auth-Token": "" } response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript example-1 const url = 'https://api.bigcommerce.com/stores/store_hash/v3/promotions/promotion_id/codes?code=TEST_COUPON&valid_from%3Amin=1756684800&valid_until%3Amax=1759276800'; const options = { method: 'GET', headers: {Accept: 'application/json', 'X-Auth-Token': ''} }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go example-1 package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/promotions/promotion_id/codes?code=TEST_COUPON&valid_from%3Amin=1756684800&valid_until%3Amax=1759276800" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Accept", "application/json") req.Header.Add("X-Auth-Token", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby example-1 require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/promotions/promotion_id/codes?code=TEST_COUPON&valid_from%3Amin=1756684800&valid_until%3Amax=1759276800") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Accept"] = 'application/json' request["X-Auth-Token"] = '' response = http.request(request) puts response.read_body ``` ```java example-1 import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.bigcommerce.com/stores/store_hash/v3/promotions/promotion_id/codes?code=TEST_COUPON&valid_from%3Amin=1756684800&valid_until%3Amax=1759276800") .header("Accept", "application/json") .header("X-Auth-Token", "") .asString(); ``` ```php example-1 request('GET', 'https://api.bigcommerce.com/stores/store_hash/v3/promotions/promotion_id/codes?code=TEST_COUPON&valid_from%3Amin=1756684800&valid_until%3Amax=1759276800', [ 'headers' => [ 'Accept' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp example-1 using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/promotions/promotion_id/codes?code=TEST_COUPON&valid_from%3Amin=1756684800&valid_until%3Amax=1759276800"); var request = new RestRequest(Method.GET); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Token", ""); IRestResponse response = client.Execute(request); ``` ```swift example-1 import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "" ] let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/promotions/promotion_id/codes?code=TEST_COUPON&valid_from%3Amin=1756684800&valid_until%3Amax=1759276800")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```