Docs
Content API
Marketing
Coupons

Coupons

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

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
    The type of discount.

    Allowed: 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
    Exclude a type of coupon.

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

example

Response

Body

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

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

  • 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

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

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

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 RFC 2822 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.

  • 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

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

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

  • 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

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 - array
    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
    Type: array[integer]

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

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

    Min: 0

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

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

  • 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

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

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

  • 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

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?
Get a Count of Store BannersGet All Coupons