Marketing

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. Optional filter parameters can be passed in.

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
Accept in header with default of application/json - string - required
The MIME type of the response body.
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
|Type| |-| |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
|Type| |-| |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
Content-Type in header with default of application/json - string - required
The MIME type of the request body.

Body

object | application/json

namestring
required
The name of the coupon.
<= 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.
Example: 0
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

idinteger
required
The coupon's ID. This is a read-only field; do not set or modify its value in a POST or PUT request.
Example: 2
date_createdstring
Date Created
Example: Tue, 13 Mar 2018 16:18:59 +0000
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.
Example: 0

namestring
required
The name of the coupon.
<= 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.
Example: 0
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

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
Accept in header with default of application/json - string - required
The MIME type of the response body.
id:in in query - string
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

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
Accept in header with default of application/json - string - required
The MIME type of the response body.

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.
Content-Type in header with default of application/json - string - required
The MIME type of the request body.

Body

object | application/json

namestring
required
The name of the coupon.
<= 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.
Example: 0
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

idinteger
required
The coupon's ID. This is a read-only field; do not set or modify its value in a POST or PUT request.
Example: 2
date_createdstring
Date Created
Example: Tue, 13 Mar 2018 16:18:59 +0000
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.
Example: 0

namestring
required
The name of the coupon.
<= 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.
Example: 0
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

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
Accept in header with default of application/json - string - required
The MIME type of the response body.
id in path - number - required
ID of the coupon.

example

Response

Get a Count of Store Banners Get All Coupons

Marketing

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

idintegerrequired

date_createdstring

num_usesinteger

namestringrequired

typestringrequired

amountstringrequired

min_purchasestring

expiresstring

enabledboolean

codestringrequired

applies_toobjectrequired

max_usesinteger

max_uses_per_customerinteger

restricted_toobject

shipping_methodsarray[string]

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

namestring
required

typestring
required

amountstring
required

codestring
required

applies_toobject
required

idinteger
required

namestring
required

typestring
required

amountstring
required

codestring
required

applies_toobject
required

namestring
required

typestring
required

amountstring
required

codestring
required

applies_toobject
required

idinteger
required

namestring
required

typestring
required

amountstring
required

codestring
required

applies_toobject
required