Beta Programs
Promotions
Promotions Single

Promotions API (Beta)

Create Promotion (Beta)

POST /promotions

Request

Creates a promotion. To learn more about how to create a promotion, read the Promotions Overview. For code samples grouped by use case, see the Code Samples section of the promotions documentation.

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

Authentication

  • X-Auth-Token in header - required

Parameters

  • store_hash in path - string
  • 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

    An auto-generated unique identifier for the discount rule.

    Example: 1

  • redemption_type
    string

    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
    required

    An internal name for this rule that the merchant can refer to.

    Example: Buy Product X Get Free Shipping

  • 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

    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.

    Example: false

  • 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.

    Example: false

    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.

  • coupon_overrides_automatic_when_offering_higher_discounts
    boolean

    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 "false", 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.

    Example: false

    Default: false

    example

    Response

    Body

    object | application/json
    • data

      Any of:
      • id
        integer

        An auto-generated unique identifier for the discount rule.

        Example: 1

      • redemption_type
        string

        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
        required

        An internal name for this rule that the merchant can refer to.

        Example: Buy Product X Get Free Shipping

      • 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

        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.

        Example: false

      • 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.

        Example: false

        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.

      • coupon_overrides_automatic_when_offering_higher_discounts
        boolean

        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 "false", 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.

        Example: false

        Default: false

    • meta
      object

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

    example

    Get Promotion (Beta)

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

    Parameters

    • store_hash in path - string
    • id in path - string - required

      The ID of the promotion in question.

    example

    Response

    Body

    object | application/json
    • data

      Any of:
      • id
        integer

        An auto-generated unique identifier for the discount rule.

        Example: 1

      • redemption_type
        string

        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
        required

        An internal name for this rule that the merchant can refer to.

        Example: Buy Product X Get Free Shipping

      • 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

        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.

        Example: false

      • 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.

        Example: false

        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.

      • coupon_overrides_automatic_when_offering_higher_discounts
        boolean

        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 "false", 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.

        Example: false

        Default: false

    • meta
      object

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

    example

    Update Promotion (Beta)

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

    Parameters

    • store_hash in path - string
    • 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

      An auto-generated unique identifier for the discount rule.

      Example: 1

    • redemption_type
      string

      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
      required

      An internal name for this rule that the merchant can refer to.

      Example: Buy Product X Get Free Shipping

    • 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

      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.

      Example: false

    • 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.

      Example: false

      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.

    • coupon_overrides_automatic_when_offering_higher_discounts
      boolean

      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 "false", 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.

      Example: false

      Default: false

      example

      Response

      Body

      object | application/json
      • data

        Any of:
        • id
          integer

          An auto-generated unique identifier for the discount rule.

          Example: 1

        • redemption_type
          string

          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
          required

          An internal name for this rule that the merchant can refer to.

          Example: Buy Product X Get Free Shipping

        • 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

          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.

          Example: false

        • 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.

          Example: false

          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.

        • coupon_overrides_automatic_when_offering_higher_discounts
          boolean

          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 "false", 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.

          Example: false

          Default: false

      • meta
        object

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

      example

      Delete Promotion (Beta)

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

      Parameters

      • store_hash in path - string
      • id in path - string - required

        The ID of the promotion in question.

      example

      Response

      The deletion was successful or the specified resource does not exist.

      Did you find what you were looking for?