> This page is for Developer. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.bigcommerce.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server. # Update Promotion PUT https://api.bigcommerce.com/stores/{store_hash}/v3/promotions/{id} Content-Type: application/json Update a promotion. **Note:** The default rate limit for this request is 40 concurrent requests. Reference: https://docs.bigcommerce.com/developer/api-reference/rest/admin/management/promotions/promotions-single/update-promotion ## Authentication - `X-Auth-Token` header (required) — ### 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](/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). For more about BigCommerce OAuth scopes, see [API Accounts and OAuth Scopes](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes). ## Request ### Path parameters - `id` (string, required) — The ID of the promotion in question. - `store_hash` (string, required) — Permanent ID of the BigCommerce store. ### Headers - `Accept` (string, required, default: application/json) — The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. ### Body (application/json) This endpoint expects a Promotions (Single)_updatePromotion_Request. - `Promotions (Single)_updatePromotion_Request` ## Response ### 200 The requested promotion. - `data` (PromotionsIdPutResponsesContentApplicationJsonSchemaData, optional) - `meta` (PromotionsIdPutResponsesContentApplicationJsonSchemaMeta, optional) — Empty meta object, which may be used at a later time. ## Errors ### 404 Not Found Error The requested resource could not be found. - `errors` (list of Error, optional) ## Types ### PatchCouponPromotion A Partial **Coupon Promotion** that contains properties to patch. - `id` (integer, optional) — An auto-generated unique identifier for the discount rule. - `redemption_type` (enum, optional) — 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`. - Allowed values: `AUTOMATIC`, `COUPON` - `name` (string, optional) — An internal name for this rule that the merchant can refer to. - `display_name` (string, optional) — Customer-facing name for this rule, that the merchant want to display to customers. - `channels` (list of Channel, optional) — 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. - `customer` (Customer, optional) — 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. - The "group_ids" array has a hard limit of 100000 group ids. - `rules` (list of Rule, optional) — An ordered list of rules to be executed until the first applicable one applies a discount successfully and the rest will be skipped. - `current_uses` (integer, optional) — 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. - `max_uses` (integer, optional) — The maximum number of times this discount can be used by customers. - `status` (enum, optional) — 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. - Allowed values: `ENABLED`, `DISABLED`, `INVALID` - `start_date` (string, optional) — The date and time when this rule will become active. - `end_date` (string, optional) — The date and time when this rule will expire. If this property is left null, the promotion never expires. - `stop` (boolean, optional) — Boolean value that specifies whether to stop evaluating promotions down the priority list when the promotion is applied successfully. - `can_be_used_with_other_promotions` (boolean, optional, default: true) — 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. - `currency_code` (string, optional) — The ISO-4217-based transactional currency code to which the promotion applies OR * for all currencies. - `notifications` (list of Notification, optional) — Notifications to display on the storefront based on the result of the evaluation for promotion eligibility. - `shipping_address` (AddressMatcher, optional) — Specifies which addresses to consider. - `schedule` (AvailabilityByWeekDay, optional) — Specifies the availability by weekdays. - `promotion_category` (enum, optional) — The category of the promotion, determined by the type of discount it applies. Promotions that discount shipping (excluding free shipping) are categorized as `shipping`; all other promotions are categorized as `cart`. This field is computed from the promotion's rules and is read-only. Featured promotions are prioritized within their category — a featured `cart` promotion does not affect the priority of `shipping` promotions, and vice versa. - Allowed values: `cart`, `shipping` - `is_featured_promotion` (boolean, optional, default: false) — Whether this promotion is a featured promotion. Featured promotion callouts are displayed to shoppers on storefront products and are evaluated at the highest priority within their category. A store can have a maximum of **5** featured promotions at any time. Featured promotions have specific constraints: - Must be an `AUTOMATIC` promotion (`redemption_type` must be `AUTOMATIC`). - Must allow stacking with other promotions (`can_be_used_with_other_promotions` must be `true`). - Must not stop evaluation of other promotions (`stop` must be `false`). - Must not have usage limits (`max_uses` must be `0` or unset). - Must not target specific shipping countries (`shipping_address` must be null or empty). - Must not target customer segments (`customer.segments` must be null or empty). - Must not use logical operators (and/or/not) in conditions. - Must not target product options or product custom fields in conditions or actions. - Must not exclude items on sale in actions. - Must contain conditions or actions that target products (brands, categories, products, or variants). When `is_featured_promotion` is included in the request, `featured_promotion_callout_message` must also be provided, and vice versa. **Priority behavior:** When a promotion is featured, it is automatically placed at the highest priority position among automatic promotions in its category (CART or SHIPPING). Featured promotions always evaluate before non-featured automatic promotions. When a promotion is un-featured, it moves to the bottom of the featured band and becomes a regular automatic promotion in the priority list. - `featured_promotion_callout_message` (string, optional) — A short customer-facing message displayed alongside the targeted products in storefront. This message highlights the promotion to shoppers. Validation rules: - Must be included in the request whenever `is_featured_promotion` is also included, and vice versa. - Required and must not be empty when `is_featured_promotion` is `true`. - Must be empty or omitted when `is_featured_promotion` is `false`. - Maximum length is **80** characters. - `codes` (CouponCode, optional) — A `CouponCode` object encapsulates attributes of a coupon code. - `coupon_overrides_automatic_when_offering_higher_discounts` (boolean, optional, default: false) — This field only has effect when `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 `fasle`, the coupon will not be applied if automatic promotions are already applied. Trying to set the value of this field to `true` when `can_be_used_with_other_promotions` is `true` will yield a 422 error response. - `coupon_type` (enum, optional) — The type of the coupon promotion, whether it will have single or multiple codes. Must be the same as existing value because changing coupon type is not supported. The field is there just for the ease of drafting PUT payload. - Allowed values: `SINGLE`, `BULK` ### PatchAutomaticPromotion A Partial **Automatic Promotion** that contains properties to patch. - `id` (integer, optional) — An auto-generated unique identifier for the discount rule. - `redemption_type` (enum, optional) — 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`. - Allowed values: `AUTOMATIC`, `COUPON` - `name` (string, optional) — An internal name for this rule that the merchant can refer to. - `display_name` (string, optional) — Customer-facing name for this rule, that the merchant want to display to customers. - `channels` (list of Channel, optional) — 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. - `customer` (Customer, optional) — 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. - The "group_ids" array has a hard limit of 100000 group ids. - `rules` (list of Rule, optional) — An ordered list of rules to be executed until the first applicable one applies a discount successfully and the rest will be skipped. - `current_uses` (integer, optional) — 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. - `max_uses` (integer, optional) — The maximum number of times this discount can be used by customers. - `status` (enum, optional) — 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. - Allowed values: `ENABLED`, `DISABLED`, `INVALID` - `start_date` (string, optional) — The date and time when this rule will become active. - `end_date` (string, optional) — The date and time when this rule will expire. If this property is left null, the promotion never expires. - `stop` (boolean, optional) — Boolean value that specifies whether to stop evaluating promotions down the priority list when the promotion is applied successfully. - `can_be_used_with_other_promotions` (boolean, optional, default: true) — 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. - `currency_code` (string, optional) — The ISO-4217-based transactional currency code to which the promotion applies OR * for all currencies. - `notifications` (list of Notification, optional) — Notifications to display on the storefront based on the result of the evaluation for promotion eligibility. - `shipping_address` (AddressMatcher, optional) — Specifies which addresses to consider. - `schedule` (AvailabilityByWeekDay, optional) — Specifies the availability by weekdays. - `promotion_category` (enum, optional) — The category of the promotion, determined by the type of discount it applies. Promotions that discount shipping (excluding free shipping) are categorized as `shipping`; all other promotions are categorized as `cart`. This field is computed from the promotion's rules and is read-only. Featured promotions are prioritized within their category — a featured `cart` promotion does not affect the priority of `shipping` promotions, and vice versa. - Allowed values: `cart`, `shipping` - `is_featured_promotion` (boolean, optional, default: false) — Whether this promotion is a featured promotion. Featured promotion callouts are displayed to shoppers on storefront products and are evaluated at the highest priority within their category. A store can have a maximum of **5** featured promotions at any time. Featured promotions have specific constraints: - Must be an `AUTOMATIC` promotion (`redemption_type` must be `AUTOMATIC`). - Must allow stacking with other promotions (`can_be_used_with_other_promotions` must be `true`). - Must not stop evaluation of other promotions (`stop` must be `false`). - Must not have usage limits (`max_uses` must be `0` or unset). - Must not target specific shipping countries (`shipping_address` must be null or empty). - Must not target customer segments (`customer.segments` must be null or empty). - Must not use logical operators (and/or/not) in conditions. - Must not target product options or product custom fields in conditions or actions. - Must not exclude items on sale in actions. - Must contain conditions or actions that target products (brands, categories, products, or variants). When `is_featured_promotion` is included in the request, `featured_promotion_callout_message` must also be provided, and vice versa. **Priority behavior:** When a promotion is featured, it is automatically placed at the highest priority position among automatic promotions in its category (CART or SHIPPING). Featured promotions always evaluate before non-featured automatic promotions. When a promotion is un-featured, it moves to the bottom of the featured band and becomes a regular automatic promotion in the priority list. - `featured_promotion_callout_message` (string, optional) — A short customer-facing message displayed alongside the targeted products in storefront. This message highlights the promotion to shoppers. Validation rules: - Must be included in the request whenever `is_featured_promotion` is also included, and vice versa. - Required and must not be empty when `is_featured_promotion` is `true`. - Must be empty or omitted when `is_featured_promotion` is `false`. - Maximum length is **80** characters. ### PromotionsIdPutResponsesContentApplicationJsonSchemaData ### PromotionsIdPutResponsesContentApplicationJsonSchemaMeta Empty meta object, which may be used at a later time. ### Error - `status` (integer, optional) - `title` (string, optional) - `type` (string, optional) ### Channel - `id` (integer, required) ### Customer 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. - The "group_ids" array has a hard limit of 100000 group ids. - `group_ids` (list of integer, optional) — 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. This has a maximum supported length of 100000 IDs. - `minimum_order_count` (integer, optional) — The minimum number of completed orders required of the customer. - `excluded_group_ids` (list of integer, optional) — 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. - `segments` (CustomerSegments, optional) ### Rule **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. - `action` (Action, required) — **Action** - `apply_once` (boolean, optional, default: true) — Setting this property to false enables the rule to run repeatedly (for example: 1 free product X for every product Y you purchase) - `stop` (boolean, optional) — Boolean value that specifies whether to stop executing all the remaining rules down the priority list when the current rule is applied successfully. - `condition` (Condition, optional) — **Condition** ### Notification **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. - `content` (string, required) — The notification content to be displayed to the user. Data from the condition and action are available allowing the message to be customized. - `type` (enum, required) - Allowed values: `UPSELL`, `ELIGIBLE`, `APPLIED` - `locations` (list of string, required) — Specifies where the notification message will be displayed. ### AddressMatcher Specifies which addresses to consider. ### AvailabilityByWeekDay Specifies the availability by weekdays. - `week_frequency` (integer, required) — Specifies the recurrence, in number of weeks, during which the promotion is available (every "x" weeks). - `week_days` (list of enum, required) — Specifies the weekdays during which the promotion is available. - Allowed values: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday` - `daily_start_time` (string, required) — Specifies the time of day from which the promotion is available. - `daily_end_time` (string, required) — Specifies the time of day until which the promotion is available. ### CouponCode A `CouponCode` object encapsulates attributes of a coupon code. - `id` (integer, required) — An auto-generated unique identifier for the coupon code. - `code` (string, required) — A unique code that can be used to manually apply a discount. Only letters, numbers, white spaces, underscores and hyphens are allowed. - `current_uses` (integer, required) — A read-only count of the times this coupon code has been used. - `created` (datetime, required) — The date and time when this coupon code was created. - `max_uses` (integer, optional) — The maximum number of times you can use this coupon code. The default value is 0, which represents unlimited uses. - `max_uses_per_customer` (integer, optional) — The maximum number of times a specific customer can use this coupon code. The default value is 0, which represents unlimited uses. - `schedule` (CouponCodeSchedule, optional, nullable) — The custom validity window of this coupon code. `null` when the code inherits the promotion's schedule. A code is custom-scheduled if and only if `schedule` is non-null. Note: the promotion object also has a field named `schedule`. That field controls on which days of the week the promotion is available, and has no relation to this field. ### SavedCouponPromotion **Coupon Promotion** A shopper must manually apply a *coupon promotion* to their cart. - `id` (integer, required) — An auto-generated unique identifier for the discount rule. - `redemption_type` (enum, required) — 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`. - Allowed values: `COUPON` - `name` (string, required) — An internal name for this rule that the merchant can refer to. - `channels` (list of Channel, required) — 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. - `customer` (Customer, required) — 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. - The "group_ids" array has a hard limit of 100000 group ids. - `rules` (list of Rule, required) — An ordered list of rules to be executed until the first applicable one applies a discount successfully and the rest will be skipped. - `current_uses` (integer, required) — 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. - `status` (enum, required) — 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. - Allowed values: `ENABLED`, `DISABLED`, `INVALID` - `start_date` (string, required) — The date and time when this rule will become active. - `stop` (boolean, required) — Boolean value that specifies whether to stop evaluating promotions down the priority list when the promotion is applied successfully. - `can_be_used_with_other_promotions` (boolean, required, default: true) — 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. - `currency_code` (string, required) — The ISO-4217-based transactional currency code to which the promotion applies OR * for all currencies. - `notifications` (list of Notification, required) — Notifications to display on the storefront based on the result of the evaluation for promotion eligibility. - `is_featured_promotion` (boolean, required, default: false) — Whether this promotion is a featured promotion. Featured promotion callouts are displayed to shoppers on storefront products and are evaluated at the highest priority within their category. A store can have a maximum of **5** featured promotions at any time. Featured promotions have specific constraints: - Must be an `AUTOMATIC` promotion (`redemption_type` must be `AUTOMATIC`). - Must allow stacking with other promotions (`can_be_used_with_other_promotions` must be `true`). - Must not stop evaluation of other promotions (`stop` must be `false`). - Must not have usage limits (`max_uses` must be `0` or unset). - Must not target specific shipping countries (`shipping_address` must be null or empty). - Must not target customer segments (`customer.segments` must be null or empty). - Must not use logical operators (and/or/not) in conditions. - Must not target product options or product custom fields in conditions or actions. - Must not exclude items on sale in actions. - Must contain conditions or actions that target products (brands, categories, products, or variants). When `is_featured_promotion` is included in the request, `featured_promotion_callout_message` must also be provided, and vice versa. **Priority behavior:** When a promotion is featured, it is automatically placed at the highest priority position among automatic promotions in its category (CART or SHIPPING). Featured promotions always evaluate before non-featured automatic promotions. When a promotion is un-featured, it moves to the bottom of the featured band and becomes a regular automatic promotion in the priority list. - `featured_promotion_callout_message` (string, required) — A short customer-facing message displayed alongside the targeted products in storefront. This message highlights the promotion to shoppers. Validation rules: - Must be included in the request whenever `is_featured_promotion` is also included, and vice versa. - Required and must not be empty when `is_featured_promotion` is `true`. - Must be empty or omitted when `is_featured_promotion` is `false`. - Maximum length is **80** characters. - `id` (integer, required) — An auto-generated unique identifier for the discount rule. - `created_from` (enum, required) — Describes which client originally created the promotion - Allowed values: `react_ui`, `legacy_ui`, `api` - `coupon_overrides_automatic_when_offering_higher_discounts` (boolean, required, default: false) — 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 `fasle`, 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. - `redemption_type` (enum, required) — The type of the promotion. Promotions applied automatically have a value of `AUTOMATIC` whereas promotions requiring a coupon have a value of `COUPON`. - Allowed values: `COUPON` - `coupon_type` (enum, required) — The type of the coupon promotion, whether it will have single or multiple codes. - Allowed values: `SINGLE`, `BULK` - `display_name` (string, optional) — Customer-facing name for this rule, that the merchant want to display to customers. - `max_uses` (integer, optional) — The maximum number of times this discount can be used by customers. - `end_date` (string, optional) — The date and time when this rule will expire. If this property is left null, the promotion never expires. - `shipping_address` (AddressMatcher, optional) — Specifies which addresses to consider. - `schedule` (AvailabilityByWeekDay, optional) — Specifies the availability by weekdays. - `promotion_category` (enum, optional) — The category of the promotion, determined by the type of discount it applies. Promotions that discount shipping (excluding free shipping) are categorized as `shipping`; all other promotions are categorized as `cart`. This field is computed from the promotion's rules and is read-only. Featured promotions are prioritized within their category — a featured `cart` promotion does not affect the priority of `shipping` promotions, and vice versa. - Allowed values: `cart`, `shipping` - `codes` (CouponCode, optional) — A `CouponCode` object encapsulates attributes of a coupon code. - `multiple_codes` (SavedCouponPromotionMultipleCodes, optional) ### SavedAutomaticPromotion The store applies *Automatic promotions* to a shopper’s cart once the promotion criteria are satisfied. The shopper cannot manually apply an *automatic promotion*. - `id` (integer, required) — An auto-generated unique identifier for the discount rule. - `redemption_type` (enum, required) — 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`. - Allowed values: `AUTOMATIC` - `name` (string, required) — An internal name for this rule that the merchant can refer to. - `channels` (list of Channel, required) — 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. - `customer` (Customer, required) — 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. - The "group_ids" array has a hard limit of 100000 group ids. - `rules` (list of Rule, required) — An ordered list of rules to be executed until the first applicable one applies a discount successfully and the rest will be skipped. - `current_uses` (integer, required) — 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. - `status` (enum, required) — 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. - Allowed values: `ENABLED`, `DISABLED`, `INVALID` - `start_date` (string, required) — The date and time when this rule will become active. - `stop` (boolean, required) — Boolean value that specifies whether to stop evaluating promotions down the priority list when the promotion is applied successfully. - `can_be_used_with_other_promotions` (boolean, required, default: true) — 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. - `currency_code` (string, required) — The ISO-4217-based transactional currency code to which the promotion applies OR * for all currencies. - `notifications` (list of Notification, required) — Notifications to display on the storefront based on the result of the evaluation for promotion eligibility. - `is_featured_promotion` (boolean, required, default: false) — Whether this promotion is a featured promotion. Featured promotion callouts are displayed to shoppers on storefront products and are evaluated at the highest priority within their category. A store can have a maximum of **5** featured promotions at any time. Featured promotions have specific constraints: - Must be an `AUTOMATIC` promotion (`redemption_type` must be `AUTOMATIC`). - Must allow stacking with other promotions (`can_be_used_with_other_promotions` must be `true`). - Must not stop evaluation of other promotions (`stop` must be `false`). - Must not have usage limits (`max_uses` must be `0` or unset). - Must not target specific shipping countries (`shipping_address` must be null or empty). - Must not target customer segments (`customer.segments` must be null or empty). - Must not use logical operators (and/or/not) in conditions. - Must not target product options or product custom fields in conditions or actions. - Must not exclude items on sale in actions. - Must contain conditions or actions that target products (brands, categories, products, or variants). When `is_featured_promotion` is included in the request, `featured_promotion_callout_message` must also be provided, and vice versa. **Priority behavior:** When a promotion is featured, it is automatically placed at the highest priority position among automatic promotions in its category (CART or SHIPPING). Featured promotions always evaluate before non-featured automatic promotions. When a promotion is un-featured, it moves to the bottom of the featured band and becomes a regular automatic promotion in the priority list. - `featured_promotion_callout_message` (string, required) — A short customer-facing message displayed alongside the targeted products in storefront. This message highlights the promotion to shoppers. Validation rules: - Must be included in the request whenever `is_featured_promotion` is also included, and vice versa. - Required and must not be empty when `is_featured_promotion` is `true`. - Must be empty or omitted when `is_featured_promotion` is `false`. - Maximum length is **80** characters. - `redemption_type` (enum, required) — The type of the promotion. Promotions applied automatically have a value of `AUTOMATIC` whereas promotions requiring a coupon have a value of `COUPON`. - Allowed values: `AUTOMATIC` - `id` (integer, required) — An auto-generated unique identifier for the discount rule. - `created_from` (enum, required) — Describes which client originally created the promotion - Allowed values: `react_ui`, `legacy_ui`, `api` - `display_name` (string, optional) — Customer-facing name for this rule, that the merchant want to display to customers. - `max_uses` (integer, optional) — The maximum number of times this discount can be used by customers. - `end_date` (string, optional) — The date and time when this rule will expire. If this property is left null, the promotion never expires. - `shipping_address` (AddressMatcher, optional) — Specifies which addresses to consider. - `schedule` (AvailabilityByWeekDay, optional) — Specifies the availability by weekdays. - `promotion_category` (enum, optional) — The category of the promotion, determined by the type of discount it applies. Promotions that discount shipping (excluding free shipping) are categorized as `shipping`; all other promotions are categorized as `cart`. This field is computed from the promotion's rules and is read-only. Featured promotions are prioritized within their category — a featured `cart` promotion does not affect the priority of `shipping` promotions, and vice versa. - Allowed values: `cart`, `shipping` ### CustomerSegments ### Action **Action** ### Condition **Condition** ### CountryAddressMatcher Specifies the countries which the promotion targets. - `countries` (list of CountryRuleInfo, required) — A list of country rules. ### NotAddressMatcher Evaluates to `true` when the child is evaluated to `false`. - `not` (CountryAddressMatcher, required) — Specifies the countries which the promotion targets. ### CouponCodeSchedule A custom validity window for a coupon code, independent of (but fully contained within) the parent promotion's schedule. - `valid_from` (datetime, required) — The date and time from which the code can be redeemed (RFC3339 UTC). Must be within the promotion's schedule. - `valid_until` (datetime, required, nullable) — The date and time until which the code can be redeemed (RFC3339 UTC). Must be after `valid_from` and within the promotion's schedule. `null` means no end, and is only allowed if the parent promotion does not have an end date. Must not be `null` if the parent promotion has an end date. ### SavedCouponPromotionMultipleCodes - `has_multiple_codes` (boolean, optional, default: false) ### CartValueAction **Cart Value Action** Applies discount on the entire cart. - `cart_value` (CartValueActionCartValue, optional) ### CartItemsAction **Cart Items Action** Applies discount on matching products in the cart. - `cart_items` (CartItemsActionCartItems, optional) ### GiftItemAction **Gift Item Action** Give a gift item for free. - `gift_item` (GiftItemActionGiftItem, optional) ### FixedPriceSetAction **Fixed Price Set Action** Sets a fixed price for a list of items. - `fixed_price_set` (FixedPriceSetActionFixedPriceSet, optional) ### ShippingAction **Shipping Action** Applies discount on shipping, optionally restricted to specific shipping zones. - `shipping` (ShippingActionShipping, optional) ### ShippingDiscountAction **Shipping Discount Action** Discounts shipping, optionally restricted to specific shipping methods. - `shipping_discount` (ShippingDiscountActionShippingDiscount, optional) ### CartCondition **Cart Condition** Condition based on the content of the current cart. - `cart` (CartConditionCart, optional) ### AndCondition **AndCondition** Evaluates to true when all children are evaluated to true. - `and` (list of CartCondition, optional) — Array of [Conditions](/developer/api-reference/rest/admin/management/promotions). ### CountryRuleInfo Country Rule - `iso2_country_code` (string, required) — Specifies the country code, in ISO 3166-1 alpha-2 format. ### CartValueActionCartValue - `discount` (Discount, required) — **Discount** - `maximum_allowed_discount_amount` (string, optional) — The maximum monetary value that can be applied as a discount. It can take any value greater than 0, up to 10000000. The application of this maximum depends on the discount type: - Discount on shipping: - Percent Discount: Maximum discount total applies to ALL shipping destinations combined. - Fixed Amount Discount: Maximum total is divided evenly amongst all shipping destinations. - Discount on products: - Percent Discount: Maximum discount total applies to ALL products combined. - Fixed Amount Discount + Each Product's price: Maximum total is divided based on existing weighting logic amongst all products. Applicable only when `as_total` is set to `false`. - Discount on order subtotal: - Maximum discount total applies to entire order total. Applicable for both Percent and Fixed Amount discounts. ### CartItemsActionCartItems - `discount` (Discount, required) — **Discount** - `maximum_allowed_discount_amount` (string, optional) — The maximum monetary value that can be applied as a discount. It can take any value greater than 0, up to 10000000. The application of this maximum depends on the discount type: - Discount on shipping: - Percent Discount: Maximum discount total applies to ALL shipping destinations combined. - Fixed Amount Discount: Maximum total is divided evenly amongst all shipping destinations. - Discount on products: - Percent Discount: Maximum discount total applies to ALL products combined. - Fixed Amount Discount + Each Product's price: Maximum total is divided based on existing weighting logic amongst all products. Applicable only when `as_total` is set to `false`. - Discount on order subtotal: - Maximum discount total applies to entire order total. Applicable for both Percent and Fixed Amount discounts. - `as_total` (boolean, optional) — 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. - `items` (ItemMatcher, optional) — **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. - `include_items_considered_by_condition` (boolean, optional) — 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. - `exclude_items_on_sale` (boolean, optional) — Setting this value to true enables the option to prevent items already on sale from being further discounted. - `strategy` (enum, optional) — 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. - Allowed values: `LEAST_EXPENSIVE`, `LEAST_EXPENSIVE_ONLY`, `MOST_EXPENSIVE`, `MOST_EXPENSIVE_ONLY` - `quantity` (integer, optional) — Specifies a quantity of matching items to discount. If no quantity is specified, an infinite number of items can be discounted. - `add_free_item` (boolean, optional) — 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%. ### GiftItemActionGiftItem - `quantity` (integer, required) — Quantity of gift item to give. - `product_id` (integer, optional) — Product ID of the gift item. - `variant_id` (integer, optional) — Variant ID of the gift item. ### FixedPriceSetActionFixedPriceSet - `quantity` (integer, required) — Quantity of items in the set that would receive the discount. - `fixed_price` (string, required) — **Money** Represents a monetary value in the store’s default currency. - `items` (ItemMatcher, optional) — **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. - `strategy` (enum, optional) — 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. - Allowed values: `LEAST_EXPENSIVE`, `LEAST_EXPENSIVE_ONLY`, `MOST_EXPENSIVE`, `MOST_EXPENSIVE_ONLY` - `exclude_items_on_sale` (boolean, optional) — Enable this option to prevent items already on sale from being further discounted. - `include_items_considered_by_condition` (boolean, optional, default: true) — 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. ### ShippingActionShipping - `zone_ids` (ShippingActionShippingZoneIds, required) - `free_shipping` (boolean, optional) — Set this property to true to provide a separate free shipping method. Read-Only. ### ShippingDiscountActionShippingDiscount - `discount` (Discount, required) — **Discount** - `method_ids` (ShippingDiscountActionShippingDiscountMethodIds, required) - `maximum_allowed_discount_amount` (string, optional) — The maximum monetary value that can be applied as a discount. It can take any value greater than 0, up to 10000000. The application of this maximum depends on the discount type: - Discount on shipping: - Percent Discount: Maximum discount total applies to ALL shipping destinations combined. - Fixed Amount Discount: Maximum total is divided evenly amongst all shipping destinations. - Discount on products: - Percent Discount: Maximum discount total applies to ALL products combined. - Fixed Amount Discount + Each Product's price: Maximum total is divided based on existing weighting logic amongst all products. Applicable only when `as_total` is set to `false`. - Discount on order subtotal: - Maximum discount total applies to entire order total. Applicable for both Percent and Fixed Amount discounts. ### CartConditionCart - `items` (ItemMatcher, optional) — **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. - `minimum_spend` (string, optional) — **Money** Represents a monetary value in the store’s default currency. - `minimum_quantity` (integer, optional) — 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. ### Discount **Discount** ### ItemMatcher **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. ### ShippingActionShippingZoneIds ### ShippingDiscountActionShippingDiscountMethodIds ### FixedDiscount **Fixed Discount** - `fixed_amount` (string, required) — **Money** Represents a monetary value in the store’s default currency. ### PercentageDiscount **Percentage Discount** - `percentage_amount` (string, required) — The amount of discount (percentage off) to apply. ### NotItemMatcher **NotItemMatcher** Evaluates to true when the child is evaluated to false. - `not` (ItemMatcher2, optional) — **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. ### AndItemMatcher **AndItemMatcher** Evaluates to true when all children are evaluated to true. - `and` (list of ItemMatcher2, optional) — Array of Item Matcher. ### OrItemMatcher **OrItemMatcher** Evaluates to true when one of its children are evaluated to true. - `or` (list of ItemMatcher2, optional) — Array of Item Matcher. ### ItemMatcher2 **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. ### NotItemMatcher2 **NotItemMatcher** Evaluates to true when the child is evaluated to false. - `not` (ItemMatcher3, optional) — **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. ### AndItemMatcher2 **AndItemMatcher** Evaluates to true when all children are evaluated to true. - `and` (list of ItemMatcher3, optional) — Array of Item Matcher. ### OrItemMatcher2 **OrItemMatcher** Evaluates to true when one of its children are evaluated to true. - `or` (list of ItemMatcher3, optional) — Array of Item Matcher. ### ItemMatcher3 **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. ### NotItemMatcher3 **NotItemMatcher** Evaluates to true when the child is evaluated to false. - `not` (SimpleItemMatcher, optional) — **Simple Item Matcher** ### AndItemMatcher3 **AndItemMatcher** Evaluates to true when all children are evaluated to true. - `and` (list of SimpleItemMatcher, optional) — Array of Item Matcher. ### OrItemMatcher3 **OrItemMatcher** Evaluates to true when one of its children are evaluated to true. - `or` (list of SimpleItemMatcher, optional) — Array of Item Matcher. ### SimpleItemMatcher **Simple Item Matcher** ### BrandsItemMatcher **BrandsItemMatcher** Brands to which the items should belong. - `brands` (list of integer, optional) — List of brand IDs. ### CategoriesItemMatcher **CategoriesItemMatcher** Categories to which the items should belong. - `categories` (list of integer, optional) — List of category IDs. ### ProductsItemMatcher **Products Item Matcher** Specific products which items should be from. - `products` (list of integer, optional) — List of product IDs. ### VariantsItemMatcher **Variants Item Matcher** Product variants which items should be from. - `variants` (list of integer, optional) — List of variant IDs. ### ProductOptionsItemMatcher 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_option` (ProductOptionsItemMatcherProductOption, optional) ### ProductCustomFieldMatcher 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` (ProductCustomFieldMatcherProductCustomField, optional) ### ProductOptionsItemMatcherProductOption - `type` (string, required) - `name` (string, required) - `values` (list of string, required) ### ProductCustomFieldMatcherProductCustomField - `name` (string, required) - `values` (list of string, required) ## Examples **Request** ```json {} ``` **Response** ```json { "data": { "can_be_used_with_other_promotions": false, "channels": [ { "id": 1 } ], "codes": { "code": "TEST-COUPON-CODE", "created": "2019-01-20T22:00:00.000Z", "current_uses": 2, "id": 1, "max_uses": 10, "max_uses_per_customer": 5, "schedule": { "valid_from": "2026-07-01T04:00:00+00:00", "valid_until": "2026-12-31T04:59:00+00:00" } }, "coupon_overrides_automatic_when_offering_higher_discounts": false, "coupon_type": "BULK", "created_from": "react_ui", "currency_code": "USD", "current_uses": 2, "customer": { "excluded_group_ids": [ 1, 2, 3 ], "group_ids": [ 1, 2, 3 ], "minimum_order_count": 1, "segments": { "id": [ "ccec121a-f9bc-4a04-809e-1fe0d8ae7fdd" ] } }, "display_name": "WOW!!! FREE SHIPPING for Product X", "end_date": "2025-12-30T01:02:03+00:00", "featured_promotion_callout_message": "Buy 2, get 10% off!", "id": 1, "is_featured_promotion": true, "max_uses": 10, "multiple_codes": { "has_multiple_codes": false }, "name": "Buy Product X Get Free Shipping", "notifications": [ { "content": "Congratulations! Youʼve received a free %ACTION.FREE_PRODUCT%!", "locations": [ "HOME_PAGE", "PRODUCT_PAGE", "CART_PAGE", "CHECKOUT_PAGE" ], "type": "UPSELL" } ], "promotion_category": "cart", "redemption_type": "COUPON", "rules": [ { "action": { "cart_value": { "discount": { "fixed_amount": "12.95" }, "maximum_allowed_discount_amount": "10" } }, "apply_once": true, "condition": { "cart": { "items": { "brands": [ 1, 2, 3 ] }, "minimum_quantity": 1, "minimum_spend": "12.95" } }, "stop": true } ], "schedule": { "daily_end_time": "23:59:00", "daily_start_time": "01:20:00", "week_days": [ "Monday" ], "week_frequency": 2 }, "shipping_address": { "countries": [ { "iso2_country_code": "US" } ] }, "start_date": "2005-12-30T01:02:03+00:00", "status": "ENABLED", "stop": false }, "meta": {} } ``` **SDK Code** ```python import requests url = "https://api.bigcommerce.com/stores/store_hash/v3/promotions/id" payload = {} headers = { "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" } response = requests.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.bigcommerce.com/stores/store_hash/v3/promotions/id'; const options = { method: 'PUT', headers: { Accept: 'application/json', 'X-Auth-Token': '', 'Content-Type': 'application/json' }, body: '{}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.bigcommerce.com/stores/store_hash/v3/promotions/id" payload := strings.NewReader("{}") req, _ := http.NewRequest("PUT", url, payload) req.Header.Add("Accept", "application/json") req.Header.Add("X-Auth-Token", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.bigcommerce.com/stores/store_hash/v3/promotions/id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.new(url) request["Accept"] = 'application/json' request["X-Auth-Token"] = '' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.put("https://api.bigcommerce.com/stores/store_hash/v3/promotions/id") .header("Accept", "application/json") .header("X-Auth-Token", "") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('PUT', 'https://api.bigcommerce.com/stores/store_hash/v3/promotions/id', [ 'body' => '{}', 'headers' => [ 'Accept' => 'application/json', 'Content-Type' => 'application/json', 'X-Auth-Token' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.bigcommerce.com/stores/store_hash/v3/promotions/id"); var request = new RestRequest(Method.PUT); request.AddHeader("Accept", "application/json"); request.AddHeader("X-Auth-Token", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Accept": "application/json", "X-Auth-Token": "", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.bigcommerce.com/stores/store_hash/v3/promotions/id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```