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

Accept

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

Content-Type

This is a banner

Banner #2

Sale Banner

$5 off

Limit by Location

Coupon Resource

Contains the banner content. Returned as a string and includes HTML formatting.

If the datetype is set as 'custom’, this field specifies the date when the banner should become visible on the storefront.

If the datetype is set as 'custom’, this field specifies the date when the banner should stop being visible on the storefront.

This specifies whether the banner should be visible during a specific date range.

If the banner is on a specific category or brand page, then the item_id will correspond the category or brand ID.

Integer value denoting whether or not the banner is visible on the storefront: 1 = visible; 0 = not visible

banner_Base

Id of the banner.
This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.


banner_Full

banner_Put

Australia Customers Discount

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.

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

What the discount applies to. Can be products or categories.

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.

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

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.

Maximum number of times this coupon can be used.

Maximum number of times each customer can use this coupon.

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

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

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](/archive/store-operations/v2-catalog-products/v2-products#list-shipping-methods) endpoint.

coupon_Base

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

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.

coupon_Full

Email of the customer who purchased the gift certificate.

Name of the customer who purchased the gift certificate.

giftCertificate_Base

Remaining value of the gift certificate. If not set, will default to the amount.

A unique string that a customer can input to redeem a gift certificate. Values greater than 20 characters will be trimmed down to the first 20 characters and returned in the response.
If this field is not set, a value will be autogenerated.

A currency code, following the ISO 4217 standard. The currency has to exist in the store first.

Gift Certificates can only be used if the transactional currency of the cart is the same as the one defined in the gift certificate. If this value is not provided, the gift certificate is created using the store's default transactional currency.

The ID of the customer placing the order.

Date on which the gift certificate is set to expire. Date displays in the Unix timestamp format.

The ID of the gift certificate. This is a READ-ONLY field; do not set or modify its value in a POST or PUT request.

Text that will be sent to the recipient, such as “Congratulations.”

Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Date displays in the Unix timestamp format.

The email theme to use in the message sent to the recipient.

giftCertificate_Full

Date on which the gift certificate is set to expire. The date must be in [RFC 2822](https://www.rfc-editor.org/rfc/rfc2822#section-3.3) format.

Date the gift certificate was purchased. If not assigned, this will be set to today’s date. Enter date in RFC-2822 format.

giftCertificate_Post

The remaining value of the gift certificate. If not set, will default to the amount.

Date on which the gift certificate is set to expire.

giftCertificate_Put

### 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](/docs/start/authentication/api-accounts). |

### Further reading

For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).

For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).

For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).

X-Auth-Token

BigCommerce

Manage coupons, banners, and gift certificates.

## Subresources

### Coupons
Category or product discounts that can be applied to orders for customers who enter a given code.

### Banners
Banners available to display on a store.

### Gift Certificates
Gift certificates available to offer to a store’s customers.

Marketing

Returns a list of *Banners*. Default sorting is by banner id, from lowest to highest.

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

min_id

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

max_id

Optional filter param `/api/v2/banners?page={number}`

page

Optional filter param `/api/v2/banners?limit={count}`

limit

Creates a *Banner*.

**Required Fields**
* name
* content
* page
* location
* date_type

**Read Only Fields**
* date_created
* id

Updates a *Banner*.

**Read Only Fields**
* date_created
* id

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


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`

id:in

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

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

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

code

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

name

type

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

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

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

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

exclude_type

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

Returns a count of all *Coupons* in the store.

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.

By default, it deletes all *Gift Certificates*.

Returns a list of *Gift Certificates*. Optional filter parameters can be passed in.

Default sorting is by gift-certificate id, from lowest to highest.

The maximum limit is 250. If a limit isn’t provided, up to 50 gift_certificates are returned by default.

order_id

to_name

to_email

from_name

from_email

Creates a *Gift Certificate*.


**Required Fields**
* to_name
* to_email
* from_name
* from_email
* amount

**Read Only Fields**
* id
* order_id

**Notes**

When a gift certificate is created through the API, no email notification is triggered to the specified recipient.

Updates a *Gift Certificate*.

**Read Only Fields**
* id
* order_id

Coupons

Get All Coupons

Create a New Coupon

Delete All Coupons

Get a Count of Coupons

Update a Coupon

Delete a Coupon