Create Promotion

POST

https://api.bigcommerce.com/stores/:store_hash/v3/promotions

POST

/stores/:store_hash/v3/promotions

curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/promotions \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "name": "Buy Product X Get Free Shipping",
  "rules": [
    {
      "action": {}
    }
  ]
}'

{
  "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": {}
}

Creates a promotion. To learn more about how to create a promotion, read the Promotions Overview. For examples grouped by use case, see the promotions examples.

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

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 API Accounts and OAuth Scopes.

Path parameters

store_hashstringRequired

Permanent ID of the BigCommerce store.

Request

This endpoint expects an object.

Draft Coupon PromotionobjectRequired

A draft Coupon Promotion to be created. A shopper must manually apply a coupon promotion to their cart.

Draft Automatic PromotionobjectRequired

A draft Automatic Promotion to be created. The store applies automatic promotions to a shopper’s cart once the promotion criteria are satisfied. The shopper cannot manually apply an automatic promotion.

Response

The requested promotion.

dataobjectOptional

metaobjectOptional

Empty meta object, which may be used at a later time.

Errors

400

Bad Request Error

403

Forbidden Error

422

Unprocessable Entity Error