Discount

Shopify Plus

The Discount resource is available to Shopify Plus merchants only.

Discounts (or discount codes) can be created, disabled, enabled and destroyed through the Shopify API.

A merchant's customers can enter the discount code during the checkout process to redeem percentage-based, fixed amount, or free shipping discounts on a specific product, collection or order. Usually, discount codes are delivered to a customer by the merchant through an email marketing campaign, direct email, or offline marketing.

What can you do with Discount?

The Shopify API lets you do the following with the Discount resource. More detailed versions of these general actions may be available:

Discount Properties

id
{ "id" : 755341827 }

The unique numeric identifier for the discount.

discount_type
{ "discount_type" : "percentage" }

Specify how the discount's value will be applied to the order. Valid values are:

  • fixed_amount: The value as a unit of the store's currency will be discounted. E.g. If value is 30 and store's currency is USD, then $30 is deducted.
  • percentage: The percent amount to discount the order, e.g. 15% off.
  • shipping: Applies a free shipping discount on orders that have a shipping rate less than or equal to the amount specified in the value property. For example, free shipping for any shipping rate that is less than or equal to $70.

code
{ "code" : "abracadabra" }

The case-insensitive discount code that customers use at checkout. Required when creating a discount. Maximum length of 255 characters.

value
{ "value" : "50.00" }

The value of the discount. Required when creating a percentage-based or fixed-amount discount. See the discount_type property to learn more about how value is interpreted.

ends_at
{ "ends_at" : "2015-08-19T20:00:00-04:00" }

The date when the discount code becomes disabled in ISO 8601 format.

starts_at
{ "starts_at" : "2015-08-19T20:00:00-04:00" }

The date the discount becomes valid for use during checkout in ISO 8601 format.

status
{ "status" : "enabled" }

The status of the discount code. Valid values are enabled, disabled, or depleted.

minimum_order_amount
{ "minimum_order_amount" : "5.00" }

The minimum value an order must reach for the discount to be allowed during checkout.

usage_limit
{ "usage_limit" : 5 }

The number of times this discount code can be redeemed. It can be redeemed by one or many customers; the usage_limit is a store-wide absolute value. Leave blank for unlimited uses.

applies_to_id
{ "applies_to_id" : 1208686404 }

The id of a collection or product that this discount code is restricted to. Leave blank for a store-wide discount. If applies_to_id is set, then the applies_to_resource property is also mandatory.

applies_once
{ "applies_once" : false }

When a discount applies to a product or collection resource, applies_once determines whether the discount should be applied once per order, or to every applicable item in the cart.

applies_once_per_customer
{ "applies_once_per_customer" : false }

Determines whether the discount should be applied once, or any number of times per customer.

applies_to_resource
{ "applies_to_resource" : "custom_collection" }

The discount code can be set to apply to only a product, smart_collection, customersavedsearch or custom_collection. If applies_to_resource is set, then applies_to_id should also be set.

times_used
{ "times_used" : 3 }

Returns a count of successful checkouts where the discount code has been used. Cannot exceed the usage_limit property.

Endpoints

POST /admin/discounts.json

Create a discount

Create a discount code "balderdash" that gives the buyer 15% off

POST /admin/discounts.json
{
  "discount": {
    "discount_type": "percentage",
    "value": "15.0",
    "code": "balderdash"
  }
}
View Response
HTTP/1.1 201 Created
{
  "discount": {
    "id": 1046288380,
    "code": "balderdash",
    "value": "15.0",
    "ends_at": null,
    "starts_at": "2016-11-09T00:00:00-05:00",
    "status": "enabled",
    "minimum_order_amount": "0.00",
    "usage_limit": null,
    "applies_to_id": null,
    "applies_once": false,
    "applies_once_per_customer": false,
    "discount_type": "percentage",
    "applies_to_resource": null,
    "times_used": 0
  }
}

Create a discount code "fortunamajor" that gives the buyer $10 off if their order total exceeds $40

POST /admin/discounts.json
{
  "discount": {
    "discount_type": "fixed_amount",
    "value": "10.00",
    "code": "fortunamajor",
    "minimum_order_amount": "40.00"
  }
}
View Response
HTTP/1.1 201 Created
{
  "discount": {
    "id": 1046288381,
    "code": "fortunamajor",
    "value": "10.00",
    "ends_at": null,
    "starts_at": "2016-11-09T00:00:00-05:00",
    "status": "enabled",
    "minimum_order_amount": "40.00",
    "usage_limit": null,
    "applies_to_id": null,
    "applies_once": false,
    "applies_once_per_customer": false,
    "discount_type": "fixed_amount",
    "applies_to_resource": null,
    "times_used": 0
  }
}

Create a free shipping discount code "quidagis?" that can be used up to 20 times by shoppers during a specific time period

POST /admin/discounts.json
{
  "discount": {
    "discount_type": "shipping",
    "code": "quidagis?",
    "starts_at": "2015-08-23T00:00:00-04:00",
    "ends_at": "2015-08-27T23:59:59-04:00",
    "usage_limit": 20
  }
}
View Response
HTTP/1.1 201 Created
{
  "discount": {
    "id": 1046288382,
    "code": "quidagis?",
    "value": "9999999.00",
    "ends_at": "2015-08-27T23:59:59-04:00",
    "starts_at": "2015-08-23T00:00:00-04:00",
    "status": "enabled",
    "minimum_order_amount": "0.00",
    "usage_limit": 20,
    "applies_to_id": null,
    "applies_once": false,
    "applies_once_per_customer": false,
    "discount_type": "shipping",
    "applies_to_resource": null,
    "times_used": 0
  }
}
GET /admin/discounts.json

List all discounts

limit

Number of results per page

(default: 15) (maximum: 200)
page

Page to show

(default: 1)

List all discounts for a store

GET /admin/discounts.json
View Response
HTTP/1.1 200 OK
{
  "discounts": [
    {
      "id": 1046288379,
      "code": "HUNDREDOFF",
      "value": "100.0",
      "ends_at": null,
      "starts_at": null,
      "status": "enabled",
      "minimum_order_amount": "0.00",
      "usage_limit": null,
      "applies_to_id": null,
      "applies_once": false,
      "applies_once_per_customer": false,
      "discount_type": "percentage",
      "applies_to_resource": null,
      "times_used": 0
    },
    {
      "id": 680866,
      "code": "TENOFF",
      "value": "10.0",
      "ends_at": null,
      "starts_at": null,
      "status": "enabled",
      "minimum_order_amount": "0.00",
      "usage_limit": null,
      "applies_to_id": null,
      "applies_once": false,
      "applies_once_per_customer": false,
      "discount_type": "percentage",
      "applies_to_resource": null,
      "times_used": 1
    },
    {
      "id": 949676421,
      "code": "xyz",
      "value": "10.00",
      "ends_at": null,
      "starts_at": null,
      "status": "disabled",
      "minimum_order_amount": "0.00",
      "usage_limit": null,
      "applies_to_id": null,
      "applies_once": false,
      "applies_once_per_customer": false,
      "discount_type": "fixed_amount",
      "applies_to_resource": null,
      "times_used": 0
    }
  ]
}
GET /admin/discounts/680866.json

Retrieve a discount

Retrieve a discount by id

GET /admin/discounts/#{id}.json
View Response
HTTP/1.1 200 OK
{
  "discount": {
    "id": 680866,
    "code": "TENOFF",
    "value": "10.0",
    "ends_at": null,
    "starts_at": null,
    "status": "enabled",
    "minimum_order_amount": "0.00",
    "usage_limit": null,
    "applies_to_id": null,
    "applies_once": false,
    "applies_once_per_customer": false,
    "discount_type": "percentage",
    "applies_to_resource": null,
    "times_used": 1
  }
}
POST /admin/discounts/680866/disable.json

Disable a discount

Disable a discount by id

POST /admin/discounts/#{id}/disable.json
{}
View Response
HTTP/1.1 201 Created
{
  "discount": {
    "id": 680866,
    "code": "TENOFF",
    "value": "10.0",
    "ends_at": null,
    "starts_at": null,
    "status": "disabled",
    "minimum_order_amount": "0.00",
    "usage_limit": null,
    "applies_to_id": null,
    "applies_once": false,
    "applies_once_per_customer": false,
    "discount_type": "percentage",
    "applies_to_resource": null,
    "times_used": 1
  }
}
POST /admin/discounts/949676421/enable.json

Enable a discount

Enable a discount by id

POST /admin/discounts/#{id}/enable.json
{}
View Response
HTTP/1.1 201 Created
{
  "discount": {
    "id": 949676421,
    "code": "xyz",
    "value": "10.00",
    "ends_at": null,
    "starts_at": null,
    "status": "enabled",
    "minimum_order_amount": "0.00",
    "usage_limit": null,
    "applies_to_id": null,
    "applies_once": false,
    "applies_once_per_customer": false,
    "discount_type": "fixed_amount",
    "applies_to_resource": null,
    "times_used": 0
  }
}
DELETE /admin/discounts/680866.json

Delete a discount

Permanently delete a discount by id

DELETE /admin/discounts/#{id}.json
View Response
HTTP/1.1 200 OK
{}