Get Promotion

GET

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

GET

/stores/:store_hash/v3/promotions/:id

curl https://api.bigcommerce.com/stores/store_hash/v3/promotions/id \
     -H "Accept: application/json" \
     -H "X-Auth-Token: <apiKey>"

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

Returns a single promotion.

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

idstringRequired

The ID of the promotion in question.

store_hashstringRequired

Permanent ID of the BigCommerce store.

Response

The requested promotion.

dataobjectOptional

metaobjectOptional

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

Errors

404

Not Found Error