List Coupons

GET

https://api.bigcommerce.com/stores/:store_hash/v2/coupons

GET

/stores/:store_hash/v2/coupons

$ curl https://api.bigcommerce.com/stores/store_hash/v2/coupons \
>      -H "Accept: application/json" \
>      -H "X-Auth-Token: <apiKey>" \
>      -H "Content-Type: application/json"

200Response

1 [
2   {
3     "amount": "5.0000",
4     "applies_to": {
5       "ids": [
6         0
7       ],
8       "entity": "categories"
9     },
10     "code": "S2549JM0Y",
11     "id": 1,
12     "name": "$5 off",
13     "type": "per_total_discount",
14     "date_created": "Tue, 13 Mar 2018 16:18:59 +0000",
15     "enabled": true,
16     "expires": "Fri, 31 Dec 2024 23:59:59 +0000",
17     "max_uses": 0,
18     "max_uses_per_customer": 0,
19     "min_purchase": "0.0000",
20     "num_uses": 2,
21     "restricted_to": {},
22     "shipping_methods": []
23   },
24   {
25     "amount": "5.0000",
26     "applies_to": {
27       "ids": [
28         0
29       ],
30       "entity": "categories"
31     },
32     "code": "E3JC79S0I",
33     "id": 2,
34     "name": "Limit by Location",
35     "type": "per_total_discount",
36     "date_created": "Tue, 12 Jun 2018 20:22:19 +0000",
37     "enabled": true,
38     "expires": "Mon, 30 Sep 2024 23:59:59 +0000",
39     "max_uses": 25,
40     "max_uses_per_customer": 0,
41     "min_purchase": "25.0000",
42     "num_uses": 0,
43     "restricted_to": {
44       "countries": "AU"
45     },
46     "shipping_methods": [
47       "shipping_endicia"
48     ]
49   }
50 ]

Returns a list of *Coupons*. Default sorting is by coupon/discount id, from lowest to highest. You can pass in optional filter parameters. We recommended using `?min_id=x&limit=y` to paginate through a large set of data because it offers better performance. ## Usage Notes Available types for `type` and `exclude_type` filters: |Type| |-| |`per_item_discount`| |`percentage_discount`| |`per_total_discount`| |`shipping_discount`| |`free_shipping`| |`promotion`| Coupons with `type=promotion` will not populate usable data for the following fields but instead be set to the following default values: ```json ... amount : 0.0000 min_purchase: 0.0000 applies_to restricted_to: [] shipping_methods : null ... ```

List Coupons

GET

https://api.bigcommerce.com/stores/:store_hash/v2/coupons

GET

/stores/:store_hash/v2/coupons

$ curl https://api.bigcommerce.com/stores/store_hash/v2/coupons \
>      -H "Accept: application/json" \
>      -H "X-Auth-Token: <apiKey>" \
>      -H "Content-Type: application/json"

200Response

1 [
2   {
3     "amount": "5.0000",
4     "applies_to": {
5       "ids": [
6         0
7       ],
8       "entity": "categories"
9     },
10     "code": "S2549JM0Y",
11     "id": 1,
12     "name": "$5 off",
13     "type": "per_total_discount",
14     "date_created": "Tue, 13 Mar 2018 16:18:59 +0000",
15     "enabled": true,
16     "expires": "Fri, 31 Dec 2024 23:59:59 +0000",
17     "max_uses": 0,
18     "max_uses_per_customer": 0,
19     "min_purchase": "0.0000",
20     "num_uses": 2,
21     "restricted_to": {},
22     "shipping_methods": []
23   },
24   {
25     "amount": "5.0000",
26     "applies_to": {
27       "ids": [
28         0
29       ],
30       "entity": "categories"
31     },
32     "code": "E3JC79S0I",
33     "id": 2,
34     "name": "Limit by Location",
35     "type": "per_total_discount",
36     "date_created": "Tue, 12 Jun 2018 20:22:19 +0000",
37     "enabled": true,
38     "expires": "Mon, 30 Sep 2024 23:59:59 +0000",
39     "max_uses": 25,
40     "max_uses_per_customer": 0,
41     "min_purchase": "25.0000",
42     "num_uses": 0,
43     "restricted_to": {
44       "countries": "AU"
45     },
46     "shipping_methods": [
47       "shipping_endicia"
48     ]
49   }
50 ]

Returns a list of Coupons. Default sorting is by coupon/discount id, from lowest to highest. You can pass in optional filter parameters. We recommended using ?min_id=x&limit=y to paginate through a large set of data because it offers better performance.

Usage Notes

Available types for type and exclude_type filters:

Type
`per_item_discount`
`percentage_discount`
`per_total_discount`
`shipping_discount`
`free_shipping`
`promotion`

Coupons with type=promotion will not populate usable data for the following fields but instead be set to the following default values:

1 ...
2 amount : 0.0000
3 min_purchase: 0.0000
4 applies_to
5 restricted_to: []
6 shipping_methods : null
7 ...

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 our [Guide to API Accounts](/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#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

store_hashstringRequired

Permanent ID of the BigCommerce store.

Headers

AcceptstringRequiredDefaults to application/json

The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.

Query parameters

idstringOptional

Optional filter param. /api/v2/coupons?id={value}

codestringOptional

Optional filter param /api/v2/coupons?code={value}

namestringOptional

Optional filter param /api/v2/coupons?name={value}

typeenumOptional

The type of discount.

min_idintegerOptional

Optional filter param /api/v2/coupons?min_id={value}

max_idintegerOptional

Optional filter param/api/v2/coupons?max_id={value}

pagedoubleOptional

Number of pages /api/v2/coupons?page={number}

limitdoubleOptional

Count per page /api/v2/coupons?limit={count}

exclude_typeenumOptional

Exclude a type of coupon.

Response

amountstring

The discount to apply to an order, as either an amount or a percentage. This field’s usage is determined by the coupon type. For example, a type of + percentage_discount would determine a percentage here.

applies_toobject

If it is not included in the PUT request, its existing value on the coupon will be cleared. Also required to be set on the POST request

codestringformat: "[a-zA-Z0-9_\ -]"<=50 characters

The coupon code that customers will use to receive their discounts. Value must be unique. Only letters, numbers, white space, underscores, and hyphens are allowed.

idinteger

The coupon’s ID. This is a read-only field; do not set or modify its value in a POST or PUT request.

namestring<=100 characters

The name of the coupon. The value must be unique.

typeenum

date_createdstring

Date Created

enabledboolean

If the coupon is enabled, this field’s value is true; otherwise, false.

expiresstring

Specifies when a coupon expires. Coupons need not have an expiry date – you can also control expiry via + max_uses or max_uses_per_customer. If you do use this date field, the value must be in RFC 2822 format.

max_usesinteger

Maximum number of times this coupon can be used.

max_uses_per_customerinteger

Maximum number of times each customer can use this coupon.

min_purchasestring

Specifies a minimum value that an order must have before the coupon can be applied to it.

num_usesinteger

Number of times this coupon has been used. This is a read-only field; do not set or modify its value in a POST or PUT request.

restricted_toobject

shipping_methodslist of strings

This is a list of shipping-method names. A shipping method must be enabled on the store to use it with a coupon. To check which shipping methods are enabled, please use the List Shipping Methods endpoint.