Coupons | BigCommerce Dev Center

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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/coupons' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

array | application/json

example

[
  {
    "id": 1,
    "name": "$5 off",
    "type": "per_total_discount",
    "amount": "5.0000",
    "min_purchase": "0.0000",
    "expires": "",
    "enabled": true,
    "code": "S2549JM0Y",
    "applies_to": {
      "entity": "categories",
      "ids": [
        0
      ]
    },
    "num_uses": 2,
    "max_uses": 0,
    "max_uses_per_customer": 0,
    "restricted_to": {},
    "shipping_methods": [],
    "date_created": "Tue, 13 Mar 2018 16:18:59 +0000"
  },
  {
    "id": 2,
    "name": "Limit by Location",
    "type": "per_total_discount",
    "amount": "5.0000",
    "min_purchase": "25.0000",
    "expires": "",
    "enabled": true,
    "code": "E3JC79S0I",
    "applies_to": {
      "entity": "categories",
      "ids": [
        0
      ]
    },
    "num_uses": 0,
    "max_uses": 25,
    "max_uses_per_customer": 0,
    "restricted_to": {
      "countries": "AU"
    },
    "shipping_methods": [
      "shipping_endicia"
    ],
    "date_created": "Tue, 12 Jun 2018 20:22:19 +0000"
  }
]

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.
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.
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

{
  "id": 2,
  "name": "Australia Customers Discount",
  "type": "per_item_discount",
  "amount": "5",
  "min_purchase": "25",
  "expires": "",
  "enabled": true,
  "code": "S2549JM0Y",
  "applies_to": {
    "entity": "categories",
    "ids": [
      0,
      3
    ]
  },
  "num_uses": 0,
  "max_uses": 25,
  "max_uses_per_customer": 0,
  "restricted_to": {
    "countries": "AU"
  },
  "shipping_methods": [
    "shipping_endicia"
  ],
  "date_created": "Tue, 13 Mar 2018 16:18:59 +0000"
}

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.
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.
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

{
  "id": 1,
  "name": "$5 off",
  "type": "per_total_discount",
  "amount": "5.0000",
  "min_purchase": "0.0000",
  "expires": "",
  "enabled": true,
  "code": "S2549JM0Y",
  "applies_to": {
    "entity": "categories",
    "ids": [
      0
    ]
  },
  "num_uses": 2,
  "max_uses": 0,
  "max_uses_per_customer": 0,
  "restricted_to": {},
  "shipping_methods": [],
  "date_created": "Tue, 13 Mar 2018 16:18:59 +0000"
}

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

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/coupons' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

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

curl --request GET \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/coupons/count' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

Response

Body

object | application/json

countinteger

example

{
  "count": 27
}

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.
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.
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

{
  "id": 2,
  "name": "Australia Customers Discount",
  "type": "per_item_discount",
  "amount": "5",
  "min_purchase": "25",
  "expires": "",
  "enabled": true,
  "code": "S2549JM0Y",
  "applies_to": {
    "entity": "categories",
    "ids": [
      0,
      3
    ]
  },
  "num_uses": 0,
  "max_uses": 25,
  "max_uses_per_customer": 0,
  "restricted_to": {
    "countries": "AU"
  },
  "shipping_methods": [
    "shipping_endicia"
  ],
  "date_created": "Tue, 13 Mar 2018 16:18:59 +0000"
}

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.
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.
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

{
  "id": 1,
  "name": "$5 off",
  "type": "per_total_discount",
  "amount": "5.0000",
  "min_purchase": "0.0000",
  "expires": "",
  "enabled": true,
  "code": "S2549JM0Y",
  "applies_to": {
    "entity": "categories",
    "ids": [
      0
    ]
  },
  "num_uses": 2,
  "max_uses": 0,
  "max_uses_per_customer": 0,
  "restricted_to": {},
  "shipping_methods": [],
  "date_created": "Tue, 13 Mar 2018 16:18:59 +0000"
}

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

curl --request DELETE \
  --url 'https://api.bigcommerce.com/stores/[store_hash]/v2/coupons/[id]' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: xxxxxxxxxxxxxxxxx'

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

Response

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