For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dev Portal
DocsAPI ReferenceLearnCommunityChangelog
DocsAPI ReferenceLearnCommunityChangelog
    • About Our APIs
  • REST
    • Overview
      • Overview
        • Abandoned Cart Emails
        • Custom Template Associations
        • Email Templates
        • Pages
        • Marketing
              • GETList Coupons
              • POSTCreate Coupon
              • DELDelete All Coupons
              • GETGet Count of Coupons
              • PUTUpdate Coupon
              • DELDelete Coupon
        • Store Content
        • Themes
        • Widgets
        • Page Widgets
      • Payments
  • GraphQL
    • Overview
  • MCP
    • Overview
Dev Portal
LogoLogo
RESTAdminContentMarketingCoupons

Update Coupon

PUT
https://api.bigcommerce.com/stores/:store_hash/v2/coupons/:id
PUT
/stores/:store_hash/v2/coupons/:id
$curl -X PUT https://api.bigcommerce.com/stores/store_hash/v2/coupons/1.1 \
>     -H "Accept: application/json" \
>     -H "X-Auth-Token: <apiKey>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "name": "Australia Customers Discount",
>  "type": "per_item_discount",
>  "amount": "5.00",
>  "code": "AUS2024SAVE",
>  "applies_to": {
>    "ids": [
>      12,
>      34
>    ],
>    "entity": "categories"
>  },
>  "min_purchase": "25.00",
>  "expires": "Fri, 31 Dec 2024 23:59:59 +0000",
>  "enabled": true,
>  "max_uses": 25,
>  "max_uses_per_customer": 1,
>  "restricted_to": {
>    "countries": "AU"
>  },
>  "shipping_methods": [
>    "shipping_endicia",
>    "shipping_fedex"
>  ]
>}'
200Response
1{
2  "amount": "5.0000",
3  "applies_to": {
4    "ids": [
5      0
6    ],
7    "entity": "categories"
8  },
9  "code": "S2549JM0Y",
10  "id": 1,
11  "name": "$5 off",
12  "type": "per_total_discount",
13  "date_created": "Tue, 13 Mar 2018 16:18:59 +0000",
14  "enabled": true,
15  "expires": "Fri, 31 Dec 2024 23:59:59 +0000",
16  "max_uses": 0,
17  "max_uses_per_customer": 0,
18  "min_purchase": "0.0000",
19  "num_uses": 2,
20  "restricted_to": {},
21  "shipping_methods": []
22}
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.
Was this page helpful?
Previous

Get Count of Coupons

Next

Delete Coupon

Built with

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

iddoubleRequired
ID of the coupon.
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.

Request

This endpoint expects an object.
namestringRequired<=100 characters
The name of the coupon. The value must be unique.
typeenumRequired
amountstringRequired

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.

codestringRequiredformat: "[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.
applies_toobjectRequired
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
min_purchasestringOptional
Specifies a minimum value that an order must have before the coupon can be applied to it.
expiresstringOptional

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.

enabledbooleanOptional

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

max_usesintegerOptional
Maximum number of times this coupon can be used.
max_uses_per_customerintegerOptional
Maximum number of times each customer can use this coupon.
restricted_toobjectOptional
shipping_methodslist of stringsOptional

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.

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.

OAuth scopes

UI NamePermissionParameter
Marketingmodifystore_v2_marketing
Marketingread-onlystore_v2_marketing_read_only

Authentication header

HeaderArgumentDescription
X-Auth-Tokenaccess_tokenFor more about API accounts that generate access_tokens, see our Guide to API Accounts.

Further reading

For example requests and more information about authenticating BigCommerce APIs, see Authentication and Example Requests.

For more about BigCommerce OAuth scopes, see our Guide to API Accounts.

For a list of API status codes, see API Status Codes.

The MIME type of the response body.