Docs
Management API
Promotions
Promotions Single

Promotions (Single)

Create Promotion

POST /promotions

Request

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-Token in header

Parameters

  • store_hash in path - string
  • Accept in header with default of application/json - string
    required
    The MIME type of the response body.
  • Content-Type in header with default of application/json - string
    required
    The MIME type of the request body.

Body

application/json
Any of:

  • id    integer
    read-only

    An auto-generated unique identifier for the discount rule.
    Example: 1

  • redemption_type    string
    required
    read-only

    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: COUPON

  • name    string
    required

    An internal name for this rule that the merchant can refer to.
    Example: Buy Product X Get Free Shipping

  • display_name    string

    Customer-facing name for this rule, that the merchant want to display to customers.
    Example: WOW!!! FREE SHIPPING for Product X

  • channels    array[object]

    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    object

    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.

  • rules    array[object]
    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
    read-only

    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.
    Example: 2

  • max_uses    integer

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

  • status    string

    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: ENABLED | DISABLED | INVALID

  • start_date    string

    The date and time when this rule will become active.
    Example: 2005-12-30T01:02:03+00:00

  • end_date    string

    The date and time when this rule will expire. If this property is left null, the promotion never expires.
    Example: 2025-12-30T01:02:03+00:00

  • stop    boolean

    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

    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.

    Default: true

  • currency_code    string

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

  • notifications    array[object]

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

  • shipping_address

    Specifies which addresses to consider.
    One of:

    • countries      array[object]
      required

      List of Country Rules

  • schedule    object

    Specifies the availability by weekdays.

  • codes    object

    A CouponCode object encapsulates attributes of a coupon code.

  • coupon_overrides_automatic_when_offering_higher_discounts    boolean

    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 when can_be_used_with_other_promotions is true will yield a 422 error response.

    Default: false

    example

    {
    "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": 0,
    "excluded_group_ids": [
    1,
    2,
    3
    ],
    "segments": {
    "id": [
    "ccec121a-f9bc-4a04-809e-1fe0d8ae7fdd"
    ]
    }
    },
    "rules": [
    {
    "action": {
    "cart_value": {
    "discount": {
    "fixed_amount": "12.95"
    }
    }
    },
    "apply_once": true,
    "stop": true,

    Response

    Body

    object | application/json

    • data

      One of:

      • id        integer
        required
        read-only

        An auto-generated unique identifier for the discount rule.
        Example: 1

      • redemption_type        string
        required
        read-only

        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: COUPON

      • name        string
        required

        An internal name for this rule that the merchant can refer to.
        Example: Buy Product X Get Free Shipping

      • display_name        string

        Customer-facing name for this rule, that the merchant want to display to customers.
        Example: WOW!!! FREE SHIPPING for Product X

      • channels        array[object]
        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        object
        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.

      • rules        array[object]
        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
        read-only

        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.
        Example: 2

      • max_uses        integer

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

      • status        string
        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: ENABLED | DISABLED | INVALID

      • start_date        string
        required

        The date and time when this rule will become active.
        Example: 2005-12-30T01:02:03+00:00

      • end_date        string

        The date and time when this rule will expire. If this property is left null, the promotion never expires.
        Example: 2025-12-30T01:02:03+00:00

      • 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

        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.

        Default: true

      • currency_code        string
        required

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

      • notifications        array[object]
        required

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

      • shipping_address

        Specifies which addresses to consider.
        One of:

        • countries          array[object]
          required

          List of Country Rules

      • schedule        object

        Specifies the availability by weekdays.

      • created_from
        required
        read-only

        Describes which client originally created the promotion

        Allowed: react_ui | legacy_ui | api

      • codes        object

        A CouponCode object encapsulates attributes of a coupon code.

      • coupon_overrides_automatic_when_offering_higher_discounts        boolean
        required

        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.

        Default: false

      • multiple_codes        object

    • meta      object

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

    example

    {
    "data": {
    "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": 0,
    "excluded_group_ids": [
    1,
    2,
    3
    ],
    "segments": {
    "id": [
    "ccec121a-f9bc-4a04-809e-1fe0d8ae7fdd"
    ]
    }
    },
    "rules": [
    {
    "action": {
    "cart_value": {
    "discount": {
    "fixed_amount": "12.95"
    }
    }

    Get Promotion

    GET /promotions/{id}

    Request

    Returns a single promotion.

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

    Authentication

    • X-Auth-Token in header

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string
      required
      The MIME type of the response body.
    • id in path - string
      required
      The ID of the promotion in question.

    example

    curl --request GET \
    --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/promotions/[id]' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'X-Auth-Token: {{token}}'

    Response

    Body

    object | application/json

    • data

      One of:

      • id        integer
        required
        read-only

        An auto-generated unique identifier for the discount rule.
        Example: 1

      • redemption_type        string
        required
        read-only

        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: COUPON

      • name        string
        required

        An internal name for this rule that the merchant can refer to.
        Example: Buy Product X Get Free Shipping

      • display_name        string

        Customer-facing name for this rule, that the merchant want to display to customers.
        Example: WOW!!! FREE SHIPPING for Product X

      • channels        array[object]
        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        object
        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.

      • rules        array[object]
        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
        read-only

        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.
        Example: 2

      • max_uses        integer

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

      • status        string
        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: ENABLED | DISABLED | INVALID

      • start_date        string
        required

        The date and time when this rule will become active.
        Example: 2005-12-30T01:02:03+00:00

      • end_date        string

        The date and time when this rule will expire. If this property is left null, the promotion never expires.
        Example: 2025-12-30T01:02:03+00:00

      • 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

        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.

        Default: true

      • currency_code        string
        required

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

      • notifications        array[object]
        required

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

      • shipping_address

        Specifies which addresses to consider.
        One of:

        • countries          array[object]
          required

          List of Country Rules

      • schedule        object

        Specifies the availability by weekdays.

      • created_from
        required
        read-only

        Describes which client originally created the promotion

        Allowed: react_ui | legacy_ui | api

      • codes        object

        A CouponCode object encapsulates attributes of a coupon code.

      • coupon_overrides_automatic_when_offering_higher_discounts        boolean
        required

        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.

        Default: false

      • multiple_codes        object

    • meta      object

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

    example

    {
    "data": {
    "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": 0,
    "excluded_group_ids": [
    1,
    2,
    3
    ],
    "segments": {
    "id": [
    "ccec121a-f9bc-4a04-809e-1fe0d8ae7fdd"
    ]
    }
    },
    "rules": [
    {
    "action": {
    "cart_value": {
    "discount": {
    "fixed_amount": "12.95"
    }
    }

    Update Promotion

    PUT /promotions/{id}

    Request

    Update a promotion.

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

    Authentication

    • X-Auth-Token in header

    Parameters

    • store_hash in path - string
    • Accept in header with default of application/json - string
      required
      The MIME type of the response body.
    • Content-Type in header with default of application/json - string
      required
      The MIME type of the request body.
    • id in path - string
      required
      The ID of the promotion in question.

    Body

    application/json
    Any of:

    • id      integer
      read-only

      An auto-generated unique identifier for the discount rule.
      Example: 1

    • redemption_type      string
      read-only

      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: AUTOMATIC | COUPON

    • name      string

      An internal name for this rule that the merchant can refer to.
      Example: Buy Product X Get Free Shipping

    • display_name      string

      Customer-facing name for this rule, that the merchant want to display to customers.
      Example: WOW!!! FREE SHIPPING for Product X

    • channels      array[object]

      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      object

      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.

    • rules      array[object]

      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
      read-only

      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.
      Example: 2

    • max_uses      integer

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

    • status      string

      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: ENABLED | DISABLED | INVALID

    • start_date      string

      The date and time when this rule will become active.
      Example: 2005-12-30T01:02:03+00:00

    • end_date      string

      The date and time when this rule will expire. If this property is left null, the promotion never expires.
      Example: 2025-12-30T01:02:03+00:00

    • stop      boolean

      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

      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.

      Default: true

    • currency_code      string

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

    • notifications      array[object]

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

    • shipping_address

      Specifies which addresses to consider.
      One of:

      • countries        array[object]
        required

        List of Country Rules

    • schedule      object

      Specifies the availability by weekdays.

    • codes      object

      A CouponCode object encapsulates attributes of a coupon code.

    • coupon_overrides_automatic_when_offering_higher_discounts      boolean

      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.

      Default: false

      example

      {
      "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": 0,
      "excluded_group_ids": [
      1,
      2,
      3
      ],
      "segments": {
      "id": [
      "ccec121a-f9bc-4a04-809e-1fe0d8ae7fdd"
      ]
      }
      },
      "rules": [
      {
      "action": {
      "cart_value": {
      "discount": {
      "fixed_amount": "12.95"
      }
      }
      },
      "apply_once": true,
      "stop": true,

      Response

      Body

      object | application/json

      • data

        One of:

        • id          integer
          required
          read-only

          An auto-generated unique identifier for the discount rule.
          Example: 1

        • redemption_type          string
          required
          read-only

          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: COUPON

        • name          string
          required

          An internal name for this rule that the merchant can refer to.
          Example: Buy Product X Get Free Shipping

        • display_name          string

          Customer-facing name for this rule, that the merchant want to display to customers.
          Example: WOW!!! FREE SHIPPING for Product X

        • channels          array[object]
          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          object
          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.

        • rules          array[object]
          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
          read-only

          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.
          Example: 2

        • max_uses          integer

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

        • status          string
          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: ENABLED | DISABLED | INVALID

        • start_date          string
          required

          The date and time when this rule will become active.
          Example: 2005-12-30T01:02:03+00:00

        • end_date          string

          The date and time when this rule will expire. If this property is left null, the promotion never expires.
          Example: 2025-12-30T01:02:03+00:00

        • 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

          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.

          Default: true

        • currency_code          string
          required

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

        • notifications          array[object]
          required

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

        • shipping_address

          Specifies which addresses to consider.
          One of:

          • countries            array[object]
            required

            List of Country Rules

        • schedule          object

          Specifies the availability by weekdays.

        • created_from
          required
          read-only

          Describes which client originally created the promotion

          Allowed: react_ui | legacy_ui | api

        • codes          object

          A CouponCode object encapsulates attributes of a coupon code.

        • coupon_overrides_automatic_when_offering_higher_discounts          boolean
          required

          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.

          Default: false

        • multiple_codes          object

      • meta        object

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

      example

      {
      "data": {
      "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": 0,
      "excluded_group_ids": [
      1,
      2,
      3
      ],
      "segments": {
      "id": [
      "ccec121a-f9bc-4a04-809e-1fe0d8ae7fdd"
      ]
      }
      },
      "rules": [
      {
      "action": {
      "cart_value": {
      "discount": {
      "fixed_amount": "12.95"
      }
      }

      Delete Promotion

      DELETE /promotions/{id}

      Request

      Deletes a promotion.

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

      Authentication

      • X-Auth-Token in header

      Parameters

      • store_hash in path - string
      • Accept in header with default of application/json - string
        required
        The MIME type of the response body.
      • id in path - string
        required
        The ID of the promotion in question.

      example

      curl --request DELETE \
      --url 'https://api.bigcommerce.com/stores/[store_hash]/v3/promotions/[id]' \
      --header 'Accept: application/json' \
      --header 'Content-Type: application/json' \
      --header 'X-Auth-Token: {{token}}'

      Response

      The deletion was successful or the specified resource does not exist.
      Did you find what you were looking for?
      Delete Multiple PromotionsCreate Promotion