Coupons

Get All Coupons

GET https://api.bigcommerce.com/stores/{store_hash}/v2/coupons

Request

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:

...
amount : 0.0000
min_purchase: 0.0000
applies_to
restricted_to: []
shipping_methods : null
...

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string
id in query - string
Optional filter param. /api/v2/coupons?id={value}
code in query - string
Optional filter param /api/v2/coupons?code={value}
name in query - string
Optional filter param /api/v2/coupons?name={value}
type in query - string
The type of discount.
Allowed: per_item_discount | percentage_discount | per_total_discount | shipping_discount | free_shipping | promotion
min_id in query - integer
Optional filter param /api/v2/coupons?min_id={value}
max_id in query - integer
Optional filter param/api/v2/coupons?max_id={value}
page in query - number
Number of pages /api/v2/coupons?page={number}
limit in query - number
Count per page /api/v2/coupons?limit={count}
exclude_type in query - string
Exclude a type of coupon.
Allowed: per_item_discount | percentage_discount | per_total_discount | shipping_discount | free_shipping | promotion

example

Response

Body

array | application/json

example

Create a New Coupon

POST https://api.bigcommerce.com/stores/{store_hash}/v2/coupons

Request

Creates a Coupon.

Required Fields

name
code
type
amount
applies_to

Read Only Fields

id
num_uses

Notes

The coupon type can be one of the following:

per_item_discount
per_total_discount
shipping_discount
free_shipping
percentage_discount

Legacy coupon codes only work with the store's default currency. Applying a coupon with any other currency other than the store's default will result in the error: "Coupons only apply to default currency."

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string

Body

object | application/json

namestring
required
The name of the coupon. The value must be unique.
<= 100 characters
Example: Australia Customers Discount
typestring
required
Allowed: per_item_discount | per_total_discount | shipping_discount | free_shipping | percentage_discount | promotion
amountstring
required
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.
Example: 5
min_purchasestring
Specifies a minimum value that an order must have before the coupon can be applied to it.
Example: 25
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 <a href="http://tools.ietf.org/html/rfc2822#section-3.3" target="_blank">RFC 2822</a> format.
enabledboolean
If the coupon is enabled, this field’s value is true; otherwise, false.
Example: true
codestring
required
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.
<= 50 characters
Example: S2549JM0Y
applies_toobject
required
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
max_usesinteger
Maximum number of times this coupon can be used.
Example: 25
max_uses_per_customerinteger
Maximum number of times each customer can use this coupon.
restricted_toobject
shipping_methodsarray[string]
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.

example

Response

Body

application/json

example

Delete All Coupons

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/coupons

Request

Usage Notes

Deleting a coupon via this endpoint will delete the coupon but not the promotion it is attached to

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string
id:in in query - array
Optional param to identify a comma-separated list of IDs for coupons to delete in a batch. /api/v2/coupons?id:in=1,2,3
Type: array[integer]

example

Response

Get a Count of Coupons

GET https://api.bigcommerce.com/stores/{store_hash}/v2/coupons/count

Request

Returns a count of all Coupons in the store.

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string

example

Response

Body

object | application/json

countinteger

example

Update a Coupon

PUT https://api.bigcommerce.com/stores/{store_hash}/v2/coupons/{id}

Request

Updates a Coupon.

Read Only Fields

id
num_uses
date_created

Notes

If the applies_to value is cleared, you can restore it to the coupon by reapplying the applies_to value in a new PUT request.

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string
id in path - number
required
ID of the coupon.

Body

object | application/json

namestring
required
The name of the coupon. The value must be unique.
<= 100 characters
Example: Australia Customers Discount
typestring
required
Allowed: per_item_discount | per_total_discount | shipping_discount | free_shipping | percentage_discount | promotion
amountstring
required
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.
Example: 5
min_purchasestring
Specifies a minimum value that an order must have before the coupon can be applied to it.
Example: 25
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 <a href="http://tools.ietf.org/html/rfc2822#section-3.3" target="_blank">RFC 2822</a> format.
enabledboolean
If the coupon is enabled, this field’s value is true; otherwise, false.
Example: true
codestring
required
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.
<= 50 characters
Example: S2549JM0Y
applies_toobject
required
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
max_usesinteger
Maximum number of times this coupon can be used.
Example: 25
max_uses_per_customerinteger
Maximum number of times each customer can use this coupon.
restricted_toobject
shipping_methodsarray[string]
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.

example

Response

Body

application/json

example

Delete a Coupon

DELETE https://api.bigcommerce.com/stores/{store_hash}/v2/coupons/{id}

Request

Deletes a Coupon.

Authentication

X-Auth-Token in header
required

Parameters

store_hash in path - string
id in path - number
required
ID of the coupon.

example

Response

Did you find what you were looking for?

Get a Count of Store Banners Get All Coupons

Coupons

Get All Coupons

Request

Usage Notes

Authentication

Parameters

example

Response

Body

example

Create a New Coupon

Request

Authentication

Parameters

Body

namestringrequired

typestringrequired

amountstringrequired

min_purchasestring

expiresstring

enabledboolean

codestringrequired

applies_toobjectrequired

max_usesinteger

max_uses_per_customerinteger

restricted_toobject

shipping_methodsarray[string]

example

Response

Body

example

Delete All Coupons

Request

Usage Notes

Authentication

Parameters

example

Response

Get a Count of Coupons

Request

Authentication

Parameters

example

Response

Body

countinteger

example

Update a Coupon

Request

Authentication

Parameters

Body

namestringrequired

typestringrequired

amountstringrequired

min_purchasestring

expiresstring

enabledboolean

codestringrequired

applies_toobjectrequired

max_usesinteger

max_uses_per_customerinteger

restricted_toobject

shipping_methodsarray[string]

example

Response

Body

example

Delete a Coupon

Request

Authentication

Parameters

example

Response

namestring
required

typestring
required

amountstring
required

codestring
required

applies_toobject
required

namestring
required

typestring
required

amountstring
required

codestring
required

applies_toobject
required