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:
- POST /admin/api/2019-10/price_rules/{price_rule_id}/discount_codes.json Creates a discount code
- PUT /admin/api/2019-10/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Updates an existing discount code
- GET /admin/api/2019-10/price_rules/{price_rule_id}/discount_codes.json Retrieves a list of discount codes
- GET /admin/api/2019-10/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Retrieves a single discount code
- GET /admin/api/2019-10/discount_codes/lookup.json?code=SUMMERSALE10OFF Retrieves the location of a discount code
- DELETE /admin/api/2019-10/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Deletes a discount code
- POST /admin/api/2019-10/price_rules/{price_rule_id}/batch.json Creates a discount code creation job
- GET /admin/api/2019-10/price_rules/{price_rule_id}/batch/{batch_id}.json Retrieves a discount code creation job
- GET /admin/api/2019-10/price_rules/{price_rule_id}/batch/{batch_id}/discount_codes.json Retrieves a list of discount codes for a discount code creation job
DiscountCode properties
code
required |
The case-insensitive discount code that customers use at checkout. (maximum: 255 characters) Use the same value for |
created_at
read-only |
The date and time (ISO 8601 format) when the discount code was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the discount code was updated. |
id
read-only |
The ID for the discount code. |
price_rule_id
read-only |
The ID for the price rule that this discount code belongs to. |
usage_count
read-only |
The number of times that the discount code has been redeemed. |
Endpoints
Create a discount code
POST /admin/api/2019-10/price_rules/507328175/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": "2021-02-05T20:38:54-05:00",
"updated_at": "2021-02-05T20:38:54-05:00"
}
}
Update the code for a discount
PUT /admin/api/2019-10/price_rules/507328175/discount_codes/507328175.json
{
"discount_code": {
"id": 507328175,
"code": "WINTERSALE20OFF"
}
}
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "WINTERSALE20OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:38:58-05:00"
}
}
page
parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
Retrieve a list of all discount codes
GET /admin/api/2019-10/price_rules/507328175/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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
]
}
Retrieve a single discount code
GET /admin/api/2019-10/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "SUMMERSALE10OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
}
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/api/2019-10/discount_codes/lookup.json?code=SUMMERSALE10OFF
View Response
HTTP/1.1 303 See Other
Delete a discount code
DELETE /admin/api/2019-10/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 204 No Content
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.
Response fields that are specific to the batch endpoint include:
status
: The state of the discount code creation job. Possible values are:queued
: The job is acknowledged, but not started.running
: The job is in process.completed
: The job has finished.
codes_count
: The number of discount codes to create.imported_count
: The number of discount codes created successfully.failed_count
: The number of discount codes that were not created successfully. Unsuccessful attempts will retry up to three times.logs
: A report that specifies when no discount codes were created because the provided data was invalid. Example responses:- "Price rule target selection can't be blank"
- "Price rule allocation method can't be blank"
Create a discount code creation job
POST /admin/api/2019-10/price_rules/507328175/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": "2021-02-05T20:38:39-05:00",
"updated_at": "2021-02-05T20:38:39-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
Retrieves a discount code creation job
Retrieve a discount code creation job
GET /admin/api/2019-10/price_rules/507328175/batch/173232803.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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
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/api/2019-10/price_rules/507328175/batch/173232803/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": {}
}
]
}
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:
- POST /admin/api/2020-01/price_rules/{price_rule_id}/discount_codes.json Creates a discount code
- PUT /admin/api/2020-01/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Updates an existing discount code
- GET /admin/api/2020-01/price_rules/{price_rule_id}/discount_codes.json Retrieves a list of discount codes
- GET /admin/api/2020-01/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Retrieves a single discount code
- GET /admin/api/2020-01/discount_codes/lookup.json?code=SUMMERSALE10OFF Retrieves the location of a discount code
- DELETE /admin/api/2020-01/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Deletes a discount code
- POST /admin/api/2020-01/price_rules/{price_rule_id}/batch.json Creates a discount code creation job
- GET /admin/api/2020-01/price_rules/{price_rule_id}/batch/{batch_id}.json Retrieves a discount code creation job
- GET /admin/api/2020-01/price_rules/{price_rule_id}/batch/{batch_id}/discount_codes.json Retrieves a list of discount codes for a discount code creation job
DiscountCode properties
code
required |
The case-insensitive discount code that customers use at checkout. (maximum: 255 characters) Use the same value for |
created_at
read-only |
The date and time (ISO 8601 format) when the discount code was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the discount code was updated. |
id
read-only |
The ID for the discount code. |
price_rule_id
read-only |
The ID for the price rule that this discount code belongs to. |
usage_count
read-only |
The number of times that the discount code has been redeemed. |
Endpoints
Create a discount code
POST /admin/api/2020-01/price_rules/507328175/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": "2021-02-05T20:38:54-05:00",
"updated_at": "2021-02-05T20:38:54-05:00"
}
}
Update the code for a discount
PUT /admin/api/2020-01/price_rules/507328175/discount_codes/507328175.json
{
"discount_code": {
"id": 507328175,
"code": "WINTERSALE20OFF"
}
}
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "WINTERSALE20OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:38:58-05:00"
}
}
page
parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
Retrieve a list of all discount codes
GET /admin/api/2020-01/price_rules/507328175/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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
]
}
Retrieve a single discount code
GET /admin/api/2020-01/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "SUMMERSALE10OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
}
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/api/2020-01/discount_codes/lookup.json?code=SUMMERSALE10OFF
View Response
HTTP/1.1 303 See Other
Delete a discount code
DELETE /admin/api/2020-01/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 204 No Content
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.
Response fields that are specific to the batch endpoint include:
status
: The state of the discount code creation job. Possible values are:queued
: The job is acknowledged, but not started.running
: The job is in process.completed
: The job has finished.
codes_count
: The number of discount codes to create.imported_count
: The number of discount codes created successfully.failed_count
: The number of discount codes that were not created successfully. Unsuccessful attempts will retry up to three times.logs
: A report that specifies when no discount codes were created because the provided data was invalid. Example responses:- "Price rule target selection can't be blank"
- "Price rule allocation method can't be blank"
Create a discount code creation job
POST /admin/api/2020-01/price_rules/507328175/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": "2021-02-05T20:38:39-05:00",
"updated_at": "2021-02-05T20:38:39-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
Retrieves a discount code creation job
Retrieve a discount code creation job
GET /admin/api/2020-01/price_rules/507328175/batch/173232803.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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
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/api/2020-01/price_rules/507328175/batch/173232803/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": {}
}
]
}
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:
- POST /admin/api/2020-04/price_rules/{price_rule_id}/discount_codes.json Creates a discount code
- PUT /admin/api/2020-04/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Updates an existing discount code
- GET /admin/api/2020-04/price_rules/{price_rule_id}/discount_codes.json Retrieves a list of discount codes
- GET /admin/api/2020-04/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Retrieves a single discount code
- GET /admin/api/2020-04/discount_codes/lookup.json?code=SUMMERSALE10OFF Retrieves the location of a discount code
- DELETE /admin/api/2020-04/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Deletes a discount code
- POST /admin/api/2020-04/price_rules/{price_rule_id}/batch.json Creates a discount code creation job
- GET /admin/api/2020-04/price_rules/{price_rule_id}/batch/{batch_id}.json Retrieves a discount code creation job
- GET /admin/api/2020-04/price_rules/{price_rule_id}/batch/{batch_id}/discount_codes.json Retrieves a list of discount codes for a discount code creation job
DiscountCode properties
code
required |
The case-insensitive discount code that customers use at checkout. (maximum: 255 characters) Use the same value for |
created_at
read-only |
The date and time (ISO 8601 format) when the discount code was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the discount code was updated. |
id
read-only |
The ID for the discount code. |
price_rule_id
read-only |
The ID for the price rule that this discount code belongs to. |
usage_count
read-only |
The number of times that the discount code has been redeemed. |
Endpoints
Create a discount code
POST /admin/api/2020-04/price_rules/507328175/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": "2021-02-05T20:38:54-05:00",
"updated_at": "2021-02-05T20:38:54-05:00"
}
}
Update the code for a discount
PUT /admin/api/2020-04/price_rules/507328175/discount_codes/507328175.json
{
"discount_code": {
"id": 507328175,
"code": "WINTERSALE20OFF"
}
}
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "WINTERSALE20OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:38:58-05:00"
}
}
page
parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
Retrieve a list of all discount codes
GET /admin/api/2020-04/price_rules/507328175/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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
]
}
Retrieve a single discount code
GET /admin/api/2020-04/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "SUMMERSALE10OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
}
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/api/2020-04/discount_codes/lookup.json?code=SUMMERSALE10OFF
View Response
HTTP/1.1 303 See Other
Delete a discount code
DELETE /admin/api/2020-04/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 204 No Content
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.
Response fields that are specific to the batch endpoint include:
status
: The state of the discount code creation job. Possible values are:queued
: The job is acknowledged, but not started.running
: The job is in process.completed
: The job has finished.
codes_count
: The number of discount codes to create.imported_count
: The number of discount codes created successfully.failed_count
: The number of discount codes that were not created successfully. Unsuccessful attempts will retry up to three times.logs
: A report that specifies when no discount codes were created because the provided data was invalid. Example responses:- "Price rule target selection can't be blank"
- "Price rule allocation method can't be blank"
Create a discount code creation job
POST /admin/api/2020-04/price_rules/507328175/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": "2021-02-05T20:38:39-05:00",
"updated_at": "2021-02-05T20:38:39-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
Retrieves a discount code creation job
Retrieve a discount code creation job
GET /admin/api/2020-04/price_rules/507328175/batch/173232803.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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
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/api/2020-04/price_rules/507328175/batch/173232803/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": {}
}
]
}
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:
- POST /admin/api/2020-07/price_rules/{price_rule_id}/discount_codes.json Creates a discount code
- PUT /admin/api/2020-07/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Updates an existing discount code
- GET /admin/api/2020-07/price_rules/{price_rule_id}/discount_codes.json Retrieves a list of discount codes
- GET /admin/api/2020-07/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Retrieves a single discount code
- GET /admin/api/2020-07/discount_codes/lookup.json?code=SUMMERSALE10OFF Retrieves the location of a discount code
- DELETE /admin/api/2020-07/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Deletes a discount code
- POST /admin/api/2020-07/price_rules/{price_rule_id}/batch.json Creates a discount code creation job
- GET /admin/api/2020-07/price_rules/{price_rule_id}/batch/{batch_id}.json Retrieves a discount code creation job
- GET /admin/api/2020-07/price_rules/{price_rule_id}/batch/{batch_id}/discount_codes.json Retrieves a list of discount codes for a discount code creation job
DiscountCode properties
code
required |
The case-insensitive discount code that customers use at checkout. (maximum: 255 characters) Use the same value for |
created_at
read-only |
The date and time (ISO 8601 format) when the discount code was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the discount code was updated. |
id
read-only |
The ID for the discount code. |
price_rule_id
read-only |
The ID for the price rule that this discount code belongs to. |
usage_count
read-only |
The number of times that the discount code has been redeemed. |
Endpoints
Create a discount code
POST /admin/api/2020-07/price_rules/507328175/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": "2021-02-05T20:38:54-05:00",
"updated_at": "2021-02-05T20:38:54-05:00"
}
}
Update the code for a discount
PUT /admin/api/2020-07/price_rules/507328175/discount_codes/507328175.json
{
"discount_code": {
"id": 507328175,
"code": "WINTERSALE20OFF"
}
}
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "WINTERSALE20OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:38:58-05:00"
}
}
page
parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
Retrieve a list of all discount codes
GET /admin/api/2020-07/price_rules/507328175/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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
]
}
Retrieve a single discount code
GET /admin/api/2020-07/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "SUMMERSALE10OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
}
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/api/2020-07/discount_codes/lookup.json?code=SUMMERSALE10OFF
View Response
HTTP/1.1 303 See Other
Delete a discount code
DELETE /admin/api/2020-07/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 204 No Content
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.
Response fields that are specific to the batch endpoint include:
status
: The state of the discount code creation job. Possible values are:queued
: The job is acknowledged, but not started.running
: The job is in process.completed
: The job has finished.
codes_count
: The number of discount codes to create.imported_count
: The number of discount codes created successfully.failed_count
: The number of discount codes that were not created successfully. Unsuccessful attempts will retry up to three times.logs
: A report that specifies when no discount codes were created because the provided data was invalid. Example responses:- "Price rule target selection can't be blank"
- "Price rule allocation method can't be blank"
Create a discount code creation job
POST /admin/api/2020-07/price_rules/507328175/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": "2021-02-05T20:38:39-05:00",
"updated_at": "2021-02-05T20:38:39-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
Retrieves a discount code creation job
Retrieve a discount code creation job
GET /admin/api/2020-07/price_rules/507328175/batch/173232803.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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
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/api/2020-07/price_rules/507328175/batch/173232803/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": {}
}
]
}
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:
- POST /admin/api/2020-10/price_rules/{price_rule_id}/discount_codes.json Creates a discount code
- PUT /admin/api/2020-10/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Updates an existing discount code
- GET /admin/api/2020-10/price_rules/{price_rule_id}/discount_codes.json Retrieves a list of discount codes
- GET /admin/api/2020-10/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Retrieves a single discount code
- GET /admin/api/2020-10/discount_codes/lookup.json?code=SUMMERSALE10OFF Retrieves the location of a discount code
- DELETE /admin/api/2020-10/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Deletes a discount code
- POST /admin/api/2020-10/price_rules/{price_rule_id}/batch.json Creates a discount code creation job
- GET /admin/api/2020-10/price_rules/{price_rule_id}/batch/{batch_id}.json Retrieves a discount code creation job
- GET /admin/api/2020-10/price_rules/{price_rule_id}/batch/{batch_id}/discount_codes.json Retrieves a list of discount codes for a discount code creation job
DiscountCode properties
code
required |
The case-insensitive discount code that customers use at checkout. (maximum: 255 characters) Use the same value for |
created_at
read-only |
The date and time (ISO 8601 format) when the discount code was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the discount code was updated. |
id
read-only |
The ID for the discount code. |
price_rule_id
read-only |
The ID for the price rule that this discount code belongs to. |
usage_count
read-only |
The number of times that the discount code has been redeemed. |
Endpoints
Create a discount code
POST /admin/api/2020-10/price_rules/507328175/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": "2021-02-05T20:38:54-05:00",
"updated_at": "2021-02-05T20:38:54-05:00"
}
}
Update the code for a discount
PUT /admin/api/2020-10/price_rules/507328175/discount_codes/507328175.json
{
"discount_code": {
"id": 507328175,
"code": "WINTERSALE20OFF"
}
}
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "WINTERSALE20OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:38:58-05:00"
}
}
page
parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
Retrieve a list of all discount codes
GET /admin/api/2020-10/price_rules/507328175/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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
]
}
Retrieve a single discount code
GET /admin/api/2020-10/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "SUMMERSALE10OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
}
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/api/2020-10/discount_codes/lookup.json?code=SUMMERSALE10OFF
View Response
HTTP/1.1 303 See Other
Delete a discount code
DELETE /admin/api/2020-10/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 204 No Content
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.
Response fields that are specific to the batch endpoint include:
status
: The state of the discount code creation job. Possible values are:queued
: The job is acknowledged, but not started.running
: The job is in process.completed
: The job has finished.
codes_count
: The number of discount codes to create.imported_count
: The number of discount codes created successfully.failed_count
: The number of discount codes that were not created successfully. Unsuccessful attempts will retry up to three times.logs
: A report that specifies when no discount codes were created because the provided data was invalid. Example responses:- "Price rule target selection can't be blank"
- "Price rule allocation method can't be blank"
Create a discount code creation job
POST /admin/api/2020-10/price_rules/507328175/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": "2021-02-05T20:38:39-05:00",
"updated_at": "2021-02-05T20:38:39-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
Retrieves a discount code creation job
Retrieve a discount code creation job
GET /admin/api/2020-10/price_rules/507328175/batch/173232803.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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
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/api/2020-10/price_rules/507328175/batch/173232803/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": {}
}
]
}
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:
- POST /admin/api/2021-01/price_rules/{price_rule_id}/discount_codes.json Creates a discount code
- PUT /admin/api/2021-01/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Updates an existing discount code
- GET /admin/api/2021-01/price_rules/{price_rule_id}/discount_codes.json Retrieves a list of discount codes
- GET /admin/api/2021-01/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Retrieves a single discount code
- GET /admin/api/2021-01/discount_codes/lookup.json?code=SUMMERSALE10OFF Retrieves the location of a discount code
- DELETE /admin/api/2021-01/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Deletes a discount code
- POST /admin/api/2021-01/price_rules/{price_rule_id}/batch.json Creates a discount code creation job
- GET /admin/api/2021-01/price_rules/{price_rule_id}/batch/{batch_id}.json Retrieves a discount code creation job
- GET /admin/api/2021-01/price_rules/{price_rule_id}/batch/{batch_id}/discount_codes.json Retrieves a list of discount codes for a discount code creation job
DiscountCode properties
code
required |
The case-insensitive discount code that customers use at checkout. (maximum: 255 characters) Use the same value for |
created_at
read-only |
The date and time (ISO 8601 format) when the discount code was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the discount code was updated. |
id
read-only |
The ID for the discount code. |
price_rule_id
read-only |
The ID for the price rule that this discount code belongs to. |
usage_count
read-only |
The number of times that the discount code has been redeemed. |
Endpoints
Create a discount code
POST /admin/api/2021-01/price_rules/507328175/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": "2021-02-05T20:38:54-05:00",
"updated_at": "2021-02-05T20:38:54-05:00"
}
}
Update the code for a discount
PUT /admin/api/2021-01/price_rules/507328175/discount_codes/507328175.json
{
"discount_code": {
"id": 507328175,
"code": "WINTERSALE20OFF"
}
}
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "WINTERSALE20OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:38:58-05:00"
}
}
page
parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
Retrieve a list of all discount codes
GET /admin/api/2021-01/price_rules/507328175/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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
]
}
Retrieve a single discount code
GET /admin/api/2021-01/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "SUMMERSALE10OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
}
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/api/2021-01/discount_codes/lookup.json?code=SUMMERSALE10OFF
View Response
HTTP/1.1 303 See Other
Delete a discount code
DELETE /admin/api/2021-01/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 204 No Content
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.
Response fields that are specific to the batch endpoint include:
status
: The state of the discount code creation job. Possible values are:queued
: The job is acknowledged, but not started.running
: The job is in process.completed
: The job has finished.
codes_count
: The number of discount codes to create.imported_count
: The number of discount codes created successfully.failed_count
: The number of discount codes that were not created successfully. Unsuccessful attempts will retry up to three times.logs
: A report that specifies when no discount codes were created because the provided data was invalid. Example responses:- "Price rule target selection can't be blank"
- "Price rule allocation method can't be blank"
Create a discount code creation job
POST /admin/api/2021-01/price_rules/507328175/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": "2021-02-05T20:38:39-05:00",
"updated_at": "2021-02-05T20:38:39-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
Retrieves a discount code creation job
Retrieve a discount code creation job
GET /admin/api/2021-01/price_rules/507328175/batch/173232803.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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
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/api/2021-01/price_rules/507328175/batch/173232803/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": {}
}
]
}
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:
- POST /admin/api/2021-04/price_rules/{price_rule_id}/discount_codes.json Creates a discount code
- PUT /admin/api/2021-04/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Updates an existing discount code
- GET /admin/api/2021-04/price_rules/{price_rule_id}/discount_codes.json Retrieves a list of discount codes
- GET /admin/api/2021-04/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Retrieves a single discount code
- GET /admin/api/2021-04/discount_codes/lookup.json?code=SUMMERSALE10OFF Retrieves the location of a discount code
- DELETE /admin/api/2021-04/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Deletes a discount code
- POST /admin/api/2021-04/price_rules/{price_rule_id}/batch.json Creates a discount code creation job
- GET /admin/api/2021-04/price_rules/{price_rule_id}/batch/{batch_id}.json Retrieves a discount code creation job
- GET /admin/api/2021-04/price_rules/{price_rule_id}/batch/{batch_id}/discount_codes.json Retrieves a list of discount codes for a discount code creation job
DiscountCode properties
code
required |
The case-insensitive discount code that customers use at checkout. (maximum: 255 characters) Use the same value for |
created_at
read-only |
The date and time (ISO 8601 format) when the discount code was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the discount code was updated. |
id
read-only |
The ID for the discount code. |
price_rule_id
read-only |
The ID for the price rule that this discount code belongs to. |
usage_count
read-only |
The number of times that the discount code has been redeemed. |
Endpoints
Create a discount code
POST /admin/api/2021-04/price_rules/507328175/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": "2021-02-05T20:38:54-05:00",
"updated_at": "2021-02-05T20:38:54-05:00"
}
}
Update the code for a discount
PUT /admin/api/2021-04/price_rules/507328175/discount_codes/507328175.json
{
"discount_code": {
"id": 507328175,
"code": "WINTERSALE20OFF"
}
}
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "WINTERSALE20OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:38:58-05:00"
}
}
page
parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
Retrieve a list of all discount codes
GET /admin/api/2021-04/price_rules/507328175/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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
]
}
Retrieve a single discount code
GET /admin/api/2021-04/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "SUMMERSALE10OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
}
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/api/2021-04/discount_codes/lookup.json?code=SUMMERSALE10OFF
View Response
HTTP/1.1 303 See Other
Delete a discount code
DELETE /admin/api/2021-04/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 204 No Content
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.
Response fields that are specific to the batch endpoint include:
status
: The state of the discount code creation job. Possible values are:queued
: The job is acknowledged, but not started.running
: The job is in process.completed
: The job has finished.
codes_count
: The number of discount codes to create.imported_count
: The number of discount codes created successfully.failed_count
: The number of discount codes that were not created successfully. Unsuccessful attempts will retry up to three times.logs
: A report that specifies when no discount codes were created because the provided data was invalid. Example responses:- "Price rule target selection can't be blank"
- "Price rule allocation method can't be blank"
Create a discount code creation job
POST /admin/api/2021-04/price_rules/507328175/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": "2021-02-05T20:38:39-05:00",
"updated_at": "2021-02-05T20:38:39-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
Retrieves a discount code creation job
Retrieve a discount code creation job
GET /admin/api/2021-04/price_rules/507328175/batch/173232803.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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
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/api/2021-04/price_rules/507328175/batch/173232803/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": {}
}
]
}
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:
- POST /admin/api/unstable/price_rules/{price_rule_id}/discount_codes.json Creates a discount code
- PUT /admin/api/unstable/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Updates an existing discount code
- GET /admin/api/unstable/price_rules/{price_rule_id}/discount_codes.json Retrieves a list of discount codes
- GET /admin/api/unstable/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Retrieves a single discount code
- GET /admin/api/unstable/discount_codes/lookup.json?code=SUMMERSALE10OFF Retrieves the location of a discount code
- GET /admin/api/unstable/discount_codes/count.json Retrieves a count of all a price rules' discount codes.
- DELETE /admin/api/unstable/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json Deletes a discount code
- POST /admin/api/unstable/price_rules/{price_rule_id}/batch.json Creates a discount code creation job
- GET /admin/api/unstable/price_rules/{price_rule_id}/batch/{batch_id}.json Retrieves a discount code creation job
- GET /admin/api/unstable/price_rules/{price_rule_id}/batch/{batch_id}/discount_codes.json Retrieves a list of discount codes for a discount code creation job
DiscountCode properties
code
required |
The case-insensitive discount code that customers use at checkout. (maximum: 255 characters) Use the same value for |
created_at
read-only |
The date and time (ISO 8601 format) when the discount code was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the discount code was updated. |
id
read-only |
The ID for the discount code. |
price_rule_id
read-only |
The ID for the price rule that this discount code belongs to. |
usage_count
read-only |
The number of times that the discount code has been redeemed. |
Endpoints
Create a discount code
POST /admin/api/unstable/price_rules/507328175/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": "2021-02-05T20:38:54-05:00",
"updated_at": "2021-02-05T20:38:54-05:00"
}
}
Update the code for a discount
PUT /admin/api/unstable/price_rules/507328175/discount_codes/507328175.json
{
"discount_code": {
"id": 507328175,
"code": "WINTERSALE20OFF"
}
}
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "WINTERSALE20OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:38:58-05:00"
}
}
page
parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.
Retrieve a list of all discount codes
GET /admin/api/unstable/price_rules/507328175/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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
]
}
Retrieve a single discount code
GET /admin/api/unstable/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 200 OK
{
"discount_code": {
"id": 507328175,
"price_rule_id": 507328175,
"code": "SUMMERSALE10OFF",
"usage_count": 0,
"created_at": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00"
}
}
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/api/unstable/discount_codes/lookup.json?code=SUMMERSALE10OFF
View Response
HTTP/1.1 303 See Other
times_used
|
Show discount codes with times used. |
times_used_min
|
Show discount codes used less than or equal to this value. |
times_used_max
|
Show discount codes used greater than or equal to this value. |
Retrieve a count of all a price rules' discount codes.
GET /admin/api/unstable/discount_codes/count.json
View Response
HTTP/1.1 200 OK
{
"count": 2
}
Delete a discount code
DELETE /admin/api/unstable/price_rules/507328175/discount_codes/507328175.json
View Response
HTTP/1.1 204 No Content
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.
Response fields that are specific to the batch endpoint include:
status
: The state of the discount code creation job. Possible values are:queued
: The job is acknowledged, but not started.running
: The job is in process.completed
: The job has finished.
codes_count
: The number of discount codes to create.imported_count
: The number of discount codes created successfully.failed_count
: The number of discount codes that were not created successfully. Unsuccessful attempts will retry up to three times.logs
: A report that specifies when no discount codes were created because the provided data was invalid. Example responses:- "Price rule target selection can't be blank"
- "Price rule allocation method can't be blank"
Create a discount code creation job
POST /admin/api/unstable/price_rules/507328175/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": "2021-02-05T20:38:39-05:00",
"updated_at": "2021-02-05T20:38:39-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
Retrieves a discount code creation job
Retrieve a discount code creation job
GET /admin/api/unstable/price_rules/507328175/batch/173232803.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": "2021-02-05T20:05:52-05:00",
"updated_at": "2021-02-05T20:05:52-05:00",
"status": "queued",
"codes_count": 3,
"imported_count": 0,
"failed_count": 0,
"logs": []
}
}
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/api/unstable/price_rules/507328175/batch/173232803/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": {}
}
]
}