BigCommerce
Theme & Content APIs
Coupons

Marketing

Get All Coupons

GET /coupons

Request

Returns a list of Coupons. Default sorting is by coupon/discount id, from lowest to highest. You can pass in optional filter parameters. We recommended using ?min_id=x&limit=y to paginate through a large set of data because it offers better performance.

Usage Notes

Available types for type and exclude_type filters:

Type
per_item_discount
percentage_discount
per_total_discount
shipping_discount
free_shipping
promotion

Coupons with type=promotion will not populate usable data for the following fields but instead be set to the following default values:

...
amount : 0.0000
min_purchase: 0.0000
applies_to
restricted_to: []
shipping_methods : null
...

Authentication

  • X-Auth-Token in header - required

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 query - string

    Optional filter param. /api/v2/coupons?id={value}

  • code in query - string

    Optional filter param /api/v2/coupons?code={value}

  • name in query - string

    Optional filter param /api/v2/coupons?name={value}

  • type in query - string

    |Type| |-| |per_item_discount| |percentage_discount| |per_total_discount| |shipping_discount| |free_shipping| |promotion|

  • min_id in query - integer

    Optional filter param /api/v2/coupons?min_id={value}

  • max_id in query - integer

    Optional filter param/api/v2/coupons?max_id={value}

  • page in query - number

    Number of pages /api/v2/coupons?page={number}

  • limit in query - number

    Count per page /api/v2/coupons?limit={count}

  • exclude_type in query - string

    |Type| |-| |per_item_discount| |percentage_discount| |per_total_discount| |shipping_discount| |free_shipping| |promotion|

example

Response

Body

array | application/json

    example

    Create a New Coupon

    POST /coupons

    Request

    Creates a Coupon.

    Required Fields

    • name
    • code
    • type
    • amount
    • applies_to

    Read Only Fields

    • id
    • num_uses

    Notes

    The coupon type can be one of the following:

    • per_item_discount
    • per_total_discount
    • shipping_discount
    • free_shipping
    • percentage_discount

    Legacy coupon codes only work with the store's default currency. Applying a coupon with any other currency other than the store's default will result in the error: "Coupons only apply to default currency."

    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

    object | application/json
    • name
      string
      required

      The name of the coupon. The value must be unique.

      <= 100 characters

      Example: Australia Customers Discount

    • type
      string
      required

      Allowed: per_item_discount | per_total_discount | shipping_discount | free_shipping | percentage_discount | promotion

    • amount
      string
      required

      The discount to apply to an order, as either an amount or a percentage. This field’s usage is determined by the coupon type. For example, a type of + percentage_discount would determine a percentage here.

      Example: 5

    • min_purchase
      string

      Specifies a minimum value that an order must have before the coupon can be applied to it.

      Example: 25

    • expires
      string

      Specifies when a coupon expires. Coupons need not have an expiry date – you can also control expiry via + max_uses or max_uses_per_customer. If you do use this date field, the value must be in <a href="http://tools.ietf.org/html/rfc2822#section-3.3" target="_blank">RFC 2822</a> format.

    • enabled
      boolean

      If the coupon is enabled, this field’s value is true; otherwise, false.

      Example: true

    • code
      string
      required

      The coupon code that customers will use to receive their discounts. Value must be unique. Only letters, numbers, white space, underscores, and hyphens are allowed.

      <= 50 characters

      Example: S2549JM0Y

    • applies_to
      object
      required

      If it is not included in the PUT request, its existing value on the coupon will be cleared. Also required to be set on the POST request

    • max_uses
      integer

      Maximum number of times this coupon can be used.

      Example: 25

    • max_uses_per_customer
      integer

      Maximum number of times each customer can use this coupon.

      Example: 0

    • restricted_to
      object

    • shipping_methods
      array[string]

      This is a list of shipping-method names. A shipping method must be enabled on the store to use it with a coupon. To check which shipping methods are enabled, please use the List Shipping Methods endpoint.

    example

    Response

    Body

    application/json
    • id
      integer
      required

      The coupon's ID. This is a read-only field; do not set or modify its value in a POST or PUT request.

      Example: 2

    • date_created
      string

      Date Created

      Example: Tue, 13 Mar 2018 16:18:59 +0000

    • num_uses
      integer

      Number of times this coupon has been used. This is a read-only field; do not set or modify its value in a POST or PUT request.

      Example: 0

    • name
      string
      required

      The name of the coupon. The value must be unique.

      <= 100 characters

      Example: Australia Customers Discount

    • type
      string
      required

      Allowed: per_item_discount | per_total_discount | shipping_discount | free_shipping | percentage_discount | promotion

    • amount
      string
      required

      The discount to apply to an order, as either an amount or a percentage. This field’s usage is determined by the coupon type. For example, a type of + percentage_discount would determine a percentage here.

      Example: 5

    • min_purchase
      string

      Specifies a minimum value that an order must have before the coupon can be applied to it.

      Example: 25

    • expires
      string

      Specifies when a coupon expires. Coupons need not have an expiry date – you can also control expiry via + max_uses or max_uses_per_customer. If you do use this date field, the value must be in <a href="http://tools.ietf.org/html/rfc2822#section-3.3" target="_blank">RFC 2822</a> format.

    • enabled
      boolean

      If the coupon is enabled, this field’s value is true; otherwise, false.

      Example: true

    • code
      string
      required

      The coupon code that customers will use to receive their discounts. Value must be unique. Only letters, numbers, white space, underscores, and hyphens are allowed.

      <= 50 characters

      Example: S2549JM0Y

    • applies_to
      object
      required

      If it is not included in the PUT request, its existing value on the coupon will be cleared. Also required to be set on the POST request

    • max_uses
      integer

      Maximum number of times this coupon can be used.

      Example: 25

    • max_uses_per_customer
      integer

      Maximum number of times each customer can use this coupon.

      Example: 0

    • restricted_to
      object

    • shipping_methods
      array[string]

      This is a list of shipping-method names. A shipping method must be enabled on the store to use it with a coupon. To check which shipping methods are enabled, please use the List Shipping Methods endpoint.

      example

      Delete All Coupons

      DELETE /coupons

      Request

      Usage Notes

      • Deleting a coupon via this endpoint will delete the coupon but not the promotion it is attached to

      Authentication

      • X-Auth-Token in header - required

      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 in query - string

        Optional param to identify a comma separated list of ids for coupons to delete in a batch. /api/v2/coupons?id:in=1,2,3

      example

      Response

      Get a Count of Coupons

      GET /coupons/count

      Request

      Returns a count of all Coupons in the store.

      Authentication

      • X-Auth-Token in header - required

      Parameters

      • store_hash in path - string
      • Accept in header with default of application/json - string - required

        The MIME type of the response body.

      example

      Response

      Body

      object | application/json
      • count
        integer

      example

      Update a Coupon

      PUT /coupons/{id}

      Request

      Updates a Coupon.

      Read Only Fields

      • id
      • num_uses
      • date_created

      Notes

      If the applies_to value is cleared, you can restore it to the coupon by reapplying the applies_to value in a new PUT request.

      Authentication

      • X-Auth-Token in header - required

      Parameters

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

        ID of the coupon.

      • Content-Type in header with default of application/json - string - required

        The MIME type of the request body.

      Body

      object | application/json
      • name
        string
        required

        The name of the coupon. The value must be unique.

        <= 100 characters

        Example: Australia Customers Discount

      • type
        string
        required

        Allowed: per_item_discount | per_total_discount | shipping_discount | free_shipping | percentage_discount | promotion

      • amount
        string
        required

        The discount to apply to an order, as either an amount or a percentage. This field’s usage is determined by the coupon type. For example, a type of + percentage_discount would determine a percentage here.

        Example: 5

      • min_purchase
        string

        Specifies a minimum value that an order must have before the coupon can be applied to it.

        Example: 25

      • expires
        string

        Specifies when a coupon expires. Coupons need not have an expiry date – you can also control expiry via + max_uses or max_uses_per_customer. If you do use this date field, the value must be in <a href="http://tools.ietf.org/html/rfc2822#section-3.3" target="_blank">RFC 2822</a> format.

      • enabled
        boolean

        If the coupon is enabled, this field’s value is true; otherwise, false.

        Example: true

      • code
        string
        required

        The coupon code that customers will use to receive their discounts. Value must be unique. Only letters, numbers, white space, underscores, and hyphens are allowed.

        <= 50 characters

        Example: S2549JM0Y

      • applies_to
        object
        required

        If it is not included in the PUT request, its existing value on the coupon will be cleared. Also required to be set on the POST request

      • max_uses
        integer

        Maximum number of times this coupon can be used.

        Example: 25

      • max_uses_per_customer
        integer

        Maximum number of times each customer can use this coupon.

        Example: 0

      • restricted_to
        object

      • shipping_methods
        array[string]

        This is a list of shipping-method names. A shipping method must be enabled on the store to use it with a coupon. To check which shipping methods are enabled, please use the List Shipping Methods endpoint.

      example

      Response

      Body

      application/json
      • id
        integer
        required

        The coupon's ID. This is a read-only field; do not set or modify its value in a POST or PUT request.

        Example: 2

      • date_created
        string

        Date Created

        Example: Tue, 13 Mar 2018 16:18:59 +0000

      • num_uses
        integer

        Number of times this coupon has been used. This is a read-only field; do not set or modify its value in a POST or PUT request.

        Example: 0

      • name
        string
        required

        The name of the coupon. The value must be unique.

        <= 100 characters

        Example: Australia Customers Discount

      • type
        string
        required

        Allowed: per_item_discount | per_total_discount | shipping_discount | free_shipping | percentage_discount | promotion

      • amount
        string
        required

        The discount to apply to an order, as either an amount or a percentage. This field’s usage is determined by the coupon type. For example, a type of + percentage_discount would determine a percentage here.

        Example: 5

      • min_purchase
        string

        Specifies a minimum value that an order must have before the coupon can be applied to it.

        Example: 25

      • expires
        string

        Specifies when a coupon expires. Coupons need not have an expiry date – you can also control expiry via + max_uses or max_uses_per_customer. If you do use this date field, the value must be in <a href="http://tools.ietf.org/html/rfc2822#section-3.3" target="_blank">RFC 2822</a> format.

      • enabled
        boolean

        If the coupon is enabled, this field’s value is true; otherwise, false.

        Example: true

      • code
        string
        required

        The coupon code that customers will use to receive their discounts. Value must be unique. Only letters, numbers, white space, underscores, and hyphens are allowed.

        <= 50 characters

        Example: S2549JM0Y

      • applies_to
        object
        required

        If it is not included in the PUT request, its existing value on the coupon will be cleared. Also required to be set on the POST request

      • max_uses
        integer

        Maximum number of times this coupon can be used.

        Example: 25

      • max_uses_per_customer
        integer

        Maximum number of times each customer can use this coupon.

        Example: 0

      • restricted_to
        object

      • shipping_methods
        array[string]

        This is a list of shipping-method names. A shipping method must be enabled on the store to use it with a coupon. To check which shipping methods are enabled, please use the List Shipping Methods endpoint.

        example

        Delete a Coupon

        DELETE /coupons/{id}

        Request

        Deletes a Coupon.

        Authentication

        • X-Auth-Token in header - required

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

          ID of the coupon.

        example

        Response

        Did you find what you were looking for?