DiscountCode

You can use the PriceRule DiscountCode resource to create discount codes that enable specific discounts to be redeemed. Merchants can distribute discount codes to their customers using a variety of means, such as an email or URL, and customers can apply these codes at checkout.

Each discount code belongs to a price rule, which holds the logic for the discount. For more information, see the PriceRule resource.

To create multiple discount codes that use the same price rule logic, use the batch endpoint. For example, you might allow merchants to create a batch of discount codes that belong to the same price rule but are each personalized for a different customer.

What you can do with DiscountCode

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

DiscountCode properties

code
required
"code": "SUMMERSALE10OFF"

The case-insensitive discount code that customers use at checkout. (maximum: 255 characters)

Use the same value for code as the title property of the associated price rule.

created_at
"created_at": "2017-03-13T16:09:54-04:00"

The date and time (ISO 8601 format) when the discount code was created.

id
"id": 9808080986

The ID for the discount code.

price_rule_id
"price_rule_id": 423748927342

The ID for the price rule that this discount code belongs to.

usage_count
"usage_count": 3

The number of times that the discount code has been redeemed.

Endpoints

POST /admin/price_rules/507328175/discount_codes.json
Creates a discount code

Create a discount code

POST /admin/price_rules/#{price_rule_id}/discount_codes.json
{
  "discount_code": {
    "code": "SUMMERSALE10OFF"
  }
}
View Response
HTTP/1.1 201 Created
{
  "discount_code": {
    "id": 1054381139,
    "price_rule_id": 507328175,
    "code": "SUMMERSALE10OFF",
    "usage_count": 0,
    "created_at": "2018-05-07T15:47:27-04:00",
    "updated_at": "2018-05-07T15:47:27-04:00"
  }
}
PUT /admin/price_rules/507328175/discount_codes/507328175.json
Updates an existing discount code

Update the code for a discount

PUT /admin/price_rules/#{price_rule_id}/discount_codes/#{discount_code_id}.json
{
  "discount_code": {
    "id": 507328175,
    "code": "WINTERSALE20OFF",
    "usage_count": 0,
    "created_at": "2018-05-07T15:33:38-04:00",
    "updated_at": "2018-05-07T15:33:38-04:00"
  }
}
View Response
HTTP/1.1 200 OK
{
  "discount_code": {
    "id": 507328175,
    "price_rule_id": 507328175,
    "code": "WINTERSALE20OFF",
    "usage_count": 0,
    "created_at": "2018-05-07T15:33:38-04:00",
    "updated_at": "2018-05-07T15:47:27-04:00"
  }
}
GET /admin/price_rules/507328175/discount_codes.json
Retrieve a list of discount codes

Retrieve a list of all discount codes

GET /admin/price_rules/#{price_rule_id}/discount_codes.json
View Response
HTTP/1.1 200 OK
{
  "discount_codes": [
    {
      "id": 507328175,
      "price_rule_id": 507328175,
      "code": "SUMMERSALE10OFF",
      "usage_count": 0,
      "created_at": "2018-05-07T15:33:38-04:00",
      "updated_at": "2018-05-07T15:33:38-04:00"
    }
  ]
}
GET /admin/price_rules/507328175/discount_codes/507328175.json
Retrieves a single discount code

Retrieve a single discount code

GET /admin/price_rules/#{price_rule_id}/discount_codes/#{discount_code_id}.json
View Response
HTTP/1.1 200 OK
{
  "discount_code": {
    "id": 507328175,
    "price_rule_id": 507328175,
    "code": "SUMMERSALE10OFF",
    "usage_count": 0,
    "created_at": "2018-05-07T15:33:38-04:00",
    "updated_at": "2018-05-07T15:33:38-04:00"
  }
}
GET /admin/discount_codes/lookup.json

Retrieves the location of a discount code.

The discount code's location is returned in the location header, not in the DiscountCode object itself. Depending on your HTTP client, the location of the discount code might follow the location header automatically.

Search for a discount code

GET /admin/discount_codes/lookup.json?code=SUMMERSALE10OFF
View Response
HTTP/1.1 303 See Other
location: https://apple.myshopify.com/admin/price_rules/507328175/discount_codes/507328175
DELETE /admin/price_rules/507328175/discount_codes/507328175.json
Deletes a discount code

Delete a discount code

DELETE /admin/price_rules/#{price_rule_id}/discount_codes/#{discount_code_id}.json
View Response
HTTP/1.1 204 No Content
POST /admin/price_rules/507328175/batch.json

Creates a discount code creation job.

The batch endpoint can be used to asynchronously create up to 100 discount codes in a single request. It enqueues and returns a discount_code_creation object that can be monitored for completion.

Create a discount code creation job

POST /admin/price_rules/#{price_rule_id}/batch.json
{
  "discount_codes": [
    {
      "code": "SUMMER1"
    },
    {
      "code": "SUMMER2"
    },
    {
      "code": "SUMMER3"
    }
  ]
}
View Response
HTTP/1.1 201 Created
{
  "discount_code_creation": {
    "id": 989355119,
    "price_rule_id": 507328175,
    "started_at": null,
    "completed_at": null,
    "created_at": "2018-05-07T15:47:29-04:00",
    "updated_at": "2018-05-07T15:47:29-04:00",
    "status": "queued",
    "codes_count": 3,
    "imported_count": 0,
    "failed_count": 0
  }
}
GET /admin/price_rules/507328175/batch/173232803.json

Retrieves a discount code creation job

Retrieve a discount code creation job

GET /admin/price_rules/#{price_rule_id}/batch/#{batch_id}.json
View Response
HTTP/1.1 200 OK
{
  "discount_code_creation": {
    "id": 173232803,
    "price_rule_id": 507328175,
    "started_at": null,
    "completed_at": null,
    "created_at": "2018-05-07T15:33:38-04:00",
    "updated_at": "2018-05-07T15:33:38-04:00",
    "status": "queued",
    "codes_count": 3,
    "imported_count": 0,
    "failed_count": 0
  }
}
GET /admin/price_rules/507328175/batch/173232803/discount_codes.json

Retrieves a list of discount codes for a discount code creation job.

Discount codes that have been successfully created include a populated id field. Discount codes that encountered errors during the creation process include a populated errors field.

Retrieve a list of discount codes for a discount code creation job

GET /admin/price_rules/#{price_rule_id}/batch/#{batch_id}/discount_codes.json
View Response
HTTP/1.1 200 OK
{
  "discount_codes": [
    {
      "id": null,
      "code": "foo",
      "errors": {}
    },
    {
      "id": null,
      "code": "",
      "errors": {}
    },
    {
      "id": null,
      "code": "bar",
      "errors": {}
    }
  ]
}