Create Promotion | BigCommerce Developer Center

import requests
url = "https://api.bigcommerce.com/stores/store_hash/v3/promotions"
payload = { "redemption_type": "COUPON" }
headers = {
    "X-Auth-Token": "<apiKey>",
    "Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

{
  "data": {
    "id": 1,
    "redemption_type": "COUPON",
    "name": "Buy Product X Get Free Shipping",
    "display_name": "WOW!!! FREE SHIPPING for Product X",
    "channels": [
      {
        "id": 1
      }
    ],
    "customer": {
      "group_ids": [
        1,
        2,
        3
      ],
      "minimum_order_count": 1,
      "excluded_group_ids": [
        1,
        2,
        3
      ],
      "segments": {
        "not": {
          "not": {
            "not": {
              "id": {}
            }
          }
        }
      }
    },
    "rules": [
      {
        "action": {
          "cart_value": {
            "discount": {
              "fixed_amount": "12.95"
            }
          }
        },
        "apply_once": true,
        "stop": true,
        "condition": {
          "cart": {
            "items": {
              "brands": [
                1,
                2,
                3
              ]
            },
            "minimum_spend": "12.95",
            "minimum_quantity": 1
          }
        }
      }
    ],
    "current_uses": 2,
    "max_uses": 10,
    "status": "ENABLED",
    "start_date": "2005-12-30T01:02:03+00:00",
    "end_date": "2025-12-30T01:02:03+00:00",
    "stop": false,
    "can_be_used_with_other_promotions": false,
    "currency_code": "USD",
    "notifications": [
      {
        "content": "Congratulations! Youʼve received a free %ACTION.FREE_PRODUCT%!",
        "type": "UPSELL",
        "locations": [
          "HOME_PAGE",
          "PRODUCT_PAGE",
          "CART_PAGE",
          "CHECKOUT_PAGE"
        ]
      }
    ],
    "shipping_address": {
      "countries": [
        {
          "iso2_country_code": "US"
        }
      ]
    },
    "schedule": {
      "week_frequency": 2,
      "week_days": [
        "Monday"
      ],
      "daily_start_time": "01:20:00",
      "daily_end_time": "23:59:00"
    },
    "created_from": "react_ui",
    "codes": {
      "id": 1,
      "code": "TEST-COUPON-CODE",
      "current_uses": 2,
      "max_uses": 10,
      "max_uses_per_customer": 5,
      "created": "2019-01-20T22:00:00.000Z"
    },
    "coupon_overrides_automatic_when_offering_higher_discounts": false,
    "multiple_codes": {
      "has_multiple_codes": false
    },
    "coupon_type": "BULK"
  },
  "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.

Creates a *promotion*. To learn more about how to create a *promotion*, read the [Promotions Overview](/developer/docs/admin/catalog-and-inventory/promotions). For examples grouped by use case, see the [promotions examples](/developer/docs/admin/catalog-and-inventory/promotions/examples/brand). **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.

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

This endpoint expects an object.

Draft Coupon PromotionobjectRequired

Draft Automatic PromotionobjectRequired

Response

dataobject

metaobject

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

Errors

400

Bad Request Error

403

Forbidden Error

422

Unprocessable Entity Error