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

Accept

Filter promotions that target those `channel IDs`.  Example: **?channels=1,2**. Note: promotions that target all the channels are included in the filtering result.

channels

code_id

code

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

Content-Type

currency_code

Query parameter that specifies the sorting direction. The default value is *asc*.

direction

A comma-separated list of promotions to filter or target with this operation.

Example: **?id:in=11,12,13,14**

id:in

Query parameter that limits the number of items displayed per page in a paginated list of resources.

limit

name

Query parameter that specifies the page number in a paginated list of resources.

page

promotion_id

redemption_type

Query parameter that specifies the field name to sort by. The default value is *id*.

sort

status

Action

AddressMatcher

**AndCondition**
Evaluates to true when all children are evaluated to true.

Array of [Conditions](/beta/promotions/rest-management).

AndCondition

AndCustomerSegmentLimitation

**AndItemMatcher**
Evaluates to true when all children are evaluated to true.

AndItemMatcher

Specifies the time of day until which the promotion is available.

Specifies the time of day from which the promotion is available.

Specifies the weekdays during which the promotion is available.

Specifies the recurrence, in number of weeks, during which the promotion is available (every "x" weeks).

AvailabilityByWeekDay

**BrandsItemMatcher**
Brands to which the items should belong.

Brands Item Matcher

Contains data about the error of the bulk action.

List all per-item errors. Use an index of an item on a request to reference an error. The example shows the first and second item on a request that has caused an error.

Bulk Action Response Error

Contains data about the bulk action response including the number of total, failed and success.

Number of items that processed successfully.

Total number of items in the bulk action.

Bulk Action Response Meta

**Cart Condition**
Condition based on the content of the current cart.

Minimum required quantity of the item in the cart for the condition to match. This field is *mandatory* when `items` are specified, but has *no effect* if `items` are not specified.

Cart Condition

**Cart Items Action**
Applies discount on matching products in the cart.

The promotion will try to add a free item to the cart automatically, but if it cannot, it will discount a matching existing cart item by 100%.

Set this value to true to distribute the discount as a total among matching items. By default, the discount applies to each item.
Example: If set to false, the discount is $10 and you have 2 eligible items for this discount in the cart, both items will be discounted by $10, with a total of $20 off the order.
If set to true, $10 will be distributed among the 2 items, weighted by their respective price. In a case where there are 2 of the same items, each item will be discounted by $5.

Setting this value to true enables the option to prevent items already on sale from being further discounted.

Setting this value to true enables you to discount items that are used to satisfy the condition. By default items that are used to satisfy the condition are excluded from receiving the discount. For example, "Buy 1 Get 1 20% off." When the cart only contains 1 item, the discount won’t apply.

Specifies a quantity of matching items to discount. If no quantity is specified, an infinite number of items can be discounted.

If the shopper has multiple items in their cart that could be discounted by this action, strategy will determine which items are discounted, for example LEAST_EXPENSIVE will sort items by their price in ascending order and discount the cheapest item first.

Cart Items Action

**Cart Value Action**
Applies discount on the entire cart.

Cart Value Action

**CategoriesItemMatcher**
Categories to which the items should belong.

Categories Item Matcher

Channel

Contains data about the response including pagination and collection totals.

Collection Meta

Specifies the countries which the promotion targets.

CountryAddressMatcher

Specifies the country code, in ISO 3166-1 alpha-2 format.

CountryRuleInfo

A `CouponCode` object encapsulates attributes of a coupon code.

A unique code that can be used to manually apply a discount. Only letters, numbers, white spaces, underscores and hyphens are allowed.

The date and time when this coupon code was created.

A read-only count of the times this coupon code has been used.

An auto-generated unique identifier for the coupon code.

The maximum number of times you can use this coupon code. The default value is 0, which represents unlimited uses.

The maximum number of times a specific customer can use this coupon code. The default value is 0, which represents unlimited uses.

Specifies the requirements which make the customer eligible for the promotion.

Note:
- Only "group_ids" or "excluded_group_ids" should be specified (have non-empty array data), but not both.
- group_id zero (0) signifies guest customers or registered customers who are not assigned to any groups.

A list of customer group IDs that the promotion will exclude. Only customers who are NOT in those groups are eligible for this promotion. When unspecified, or set to an empty array, this requirement will not have any effects, and all customers who satisfy the other requirements (group_ids, minimum_order_count) are eligible for the promotion.

A list of customer group IDs that the promotion targets. Only customers in those groups are eligible for this promotion. When unspecified, or set to an empty array, this requirement is not effective, and all customers who satisfy the other requirements (minimum_order_count, excluded_group_ids) are eligible for the promotion.

The minimum number of completed orders required of the customer.

CustomerSegmentIdLimitation

CustomerSegmentLimitation

Discount

Error

Error Response

Fixed Discount

**Fixed Price Set Action**
Sets a fixed price for a list of items.

Enable this option to prevent items already on sale from being further discounted.

Setting this value to false enables you to exclude items used to satisfy the condition to be discounted. By default, items that are used to satisfy the condition are eligible to receive the discount.

Quantity of items in the set that would receive the discount.

If the shopper has multiple items in their cart that could be discounted by this action, strategy will determine which items are discounted, for example LEAST_EXPENSIVE will sort items in price ascending order and discount the cheapest item first.

Fixed Price Set Action

**Gift Item Action**
Give a gift item for free.

**ItemMatcher**
Lists which items to consider in the condition or action. If this is specified, you will need to also specify at least one of minimum_quantity or minimum_spend.

Item Matcher

**Money**
Represents a monetary value in the store’s default currency.

Money

Evaluates to `true` when the child is evaluated to `false`.

NotAddressMatcher

NotCustomerSegmentLimitation

**NotItemMatcher**
Evaluates to true when the child is evaluated to false.

NotItemMatcher

**Notification**
A notification displayed to the user based on the result of executing a promotion, for example, a "Congratulations! Youʼve received free shipping!" message when the shopper receives free shipping.

The notification content to be displayed to the user.
Data from the condition and action are available allowing the message to be customized.

Specifies where the notification message will be displayed.

Notification

OrCustomerSegmentLimitation

**OrItemMatcher**
Evaluates to true when one of its children are evaluated to true.

OrItemMatcher

Data about the response, including pagination and collection totals.

Total number of items in the collection response.

The page you are currently on within the collection.

Pagination links for the previous and next parts of the whole collection.

Link to the current page returned in the response.

Link to the next page returned in the response.

Link to the previous page returned in the response.

The amount of items returned in the collection per page, controlled by the limit of items per page parameter.

The total number of pages in the collection.

Pagination

The amount of discount (percentage off) to apply.

Percentage Discount

Match a product with a custom field.

You can define a maximum of 10 Product Custom Field Item Matchers within an Item Matcher.

Product Custom Field Item Matcher

Match a product by product options.

Currently the only supported type is `string_match` which performs a string comparison on the name and values.

Product Options Item Matcher

**Products Item Matcher**
Specific products which items should be from.

Products Item Matcher

The store applies *automatic promotions* to a shopper’s cart once the promotion criteria are satisfied. The shopper cannot manually apply an *automatic promotion*.

Automatic Promotion

**Promotion**
A *promotion* is composed of a condition that a customer can satisfy (such as increasing their cart value above a certain amount or adding an item to their cart) and an action will take place (such as a discount on the customer’s order total, or a free item being added to their cart).

Boolean value that specifies whether this promotion can be used with other promotions. When set to false, only apply this promotion if there are no discounts applied already, and stop executing other promotions if this promotion applies successfully.

Channels that the promotion targets. Empty array [] means targeting all the channels. In POST request, if omitted, this field defaults to an empty array [] value.

The ISO-4217-based transactional currency code to which the promotion applies OR * for all currencies.

A read-only count of the times this rule has been used by customers. A rule is considered to be used when a customer successfully checks out with a rule that has applied a discount to their cart.

The date and time when this rule will expire. If this property is left null, the promotion never expires.

An auto-generated unique identifier for the discount rule.

The maximum number of times this discount can be used by customers.

An internal name for this rule that the merchant can refer to.

Notifications to display on the storefront based on the result of the evaluation for promotion eligibility.

A read-only field indicating the type of promotion. Promotions applied automatically have a value of `AUTOMATIC` whereas promotions requiring a coupon have a value of `COUPON`.

An ordered list of rules to be executed until the first applicable one applies a discount successfully and the rest will be skipped.

The date and time when this rule will become active.

Controls whether or not a discount rule can be used by customers. `INVALID` is a read-only status into which enabled discount rules may transition when they become invalid.

Boolean value that specifies whether to stop evaluating promotions down the priority list when the promotion is applied successfully.

PromotionBase

This field only has effect when the `redemption_type` is `COUPON` and `can_be_used_with_other_promotions` is `false`:
- When the property is set to "true", the coupon will override the applied automatic promotions if it provides a greater discount.
- When the property is set to "false", the coupon will not be applied if automatic promotions are already applied.

Trying to set the value of this field to "true" when the `redemption_type` is not `COUPON`, or when `can_be_used_with_other_promotions` is `true` will yield a 422 error response.

**Coupon Promotion** A shopper must manually apply a *coupon promotion* to their cart.

Coupon Promotion

**Rule**
A Rule is the executable unit of the promotion. When a ruleʼs condition is met, the API applies the discount defined in the specified action.

Setting this property to false enables the rule to run repeatedly (for example: 1 free product X for every product Y you purchase)

Boolean value that specifies whether to stop executing all the remaining rules down the priority list when the current rule is applied successfully.

Rule

**Shipping Action**
Applies discount on shipping, optionally restricted to specific shipping zones.

Set this property to true to provide a separate free shipping method. Read-Only.

Shipping Action

Simple Item Matcher

**Variants Item Matcher**
Product variants which items should be from.

Variants Item Matcher

### 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 [API Accounts and OAuth Scopes](/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).

For more about BigCommerce OAuth scopes, see [API Accounts and OAuth Scopes](/docs/start/authentication/api-accounts).

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

X-Auth-Token

BigCommerce

## This API is currently in BETA.

A *promotion* is composed of a condition that a customer can satisfy, such as increasing their cart value above a certain amount or adding an item to their cart. 

After the customer satisfies the condition, an action takes place, such as a free item being added to the cart or a discount applying itself to the order total.

To learn more about promotions, consult the [Promotions Overview](/beta/promotions).

Promotions API (Beta)

Deletes multiple promotions. Currently, batches are limited to 50 promotions.

**Notes**
* "id:in" query param is required to delete promotions. If this parameter is not provided, or provided with the wrong data format, a 422 error code is returned.
* You cannot delete promotions that still have coupon codes attached.
* The default rate limit for this endpoint is 40 concurrent requests.

Returns a list of *promotions*.

The response includes the display name and other details about each promotion, and lists the promotions ordered by ID by default.

**Note:**
The default rate limit for this endpoint is 40 concurrent requests.

Failure due to an invalid query parameter.

Creates a *promotion*.
To learn more about how to create a *promotion*, read the [Promotions Overview](/beta/promotions).
For code samples grouped by use case, see the [Code Samples](/beta/promotions/code-samples/brand) section of the promotions documentation.

**Note:**
The default rate limit for this endpoint is 40 concurrent requests.

Deletes a promotion.

**Note:**
The default rate limit for this endpoint is 40 concurrent requests.

The deletion was successful or the specified resource does not exist.

Returns a single *promotion*.

**Note:**
The default rate limit for this endpoint is 40 concurrent requests

Update a promotion.

**Note:**
The default rate limit for this request is 40 concurrent requests.

The requested resource could not be found.

Deletes multiple coupon codes relating to the given promotion. Currently, batches are limited to 50 coupon codes.

**Notes**
* "id:in" query param is required to delete coupon codes. If not provided, or provided with the wrong data format, a 422 error code is returned.
* The default rate limit for this endpoint is 40 concurrent requests.

Get codes for a particular promotion.

**Note:**
The default rate limit for this endpoint is 40 concurrent requests.

Create a new code for the promotion.

**Note:**
The default rate limit for this endpoint is 40 concurrent requests.

Deletes a coupon code.

**Note:**
The default rate limit for this endpoint is 40 concurrent requests.

The deletion was successful or the resource does not exist.

Promotions API (Beta)

Get Coupon Codes (Beta)

Request

Authentication

Parameters

example

Response

Body

dataarray[object]

metaobject

example-1

Delete Multiple Coupon Codes (Beta)

Request

Authentication

Parameters

example

Response