# DiscountCode

Note

We recommend using the GraphQL Admin API to manage discounts. The Discount types available in the GraphQL Admin API are intended to replace the GraphQL Admin PriceRule object and REST Admin PriceRule and DiscountCode resources.

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.

## Resource Properties ### DiscountCode * code:

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.

* Type: x-string * Example: "SUMMERSALE10OFF" * created_at:

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

* Type: x-string * Example: "2017-03-13T16:09:54-04:00" * updated_at:

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

* Type: x-string * Example: "2017-03-13T16:09:54-04:00" * id: The ID for the discount code. * Type: x-string * Example: 9808080986 * price_rule_id: The ID for the price rule that this discount code belongs to. * Type: x-string * Example: 423748927342 * usage_count: The number of times that the discount code has been redeemed. * Type: x-string * Example: 3 * errors: An array of errors that occurred when retrieving a list of discount codes for a discount code creation job. * Type: x-string * Example: {"code"=>["must be unique. Please try a different code."]} ## Creates a discount code

Creates a discount code.

The price_rule_id path parameter is the ID of the price rule that the discount code will belong to. This is required because each discount code must belong to a price rule.

### Endpoint /admin/api/#{api_version}/price_rules/{price_rule_id}/discount_codes.json (POST) ### Parameters * api_version (required): * price_rule_id (required): ### Responses #### 201 Creates a discount code Examples: ##### Create a discount code Request: ``` POST /admin/api/unstable/price_rules/507328175/discount_codes.json {"discount_code":{"code":"SUMMERSALE10OFF"}} ``` Response: ``` HTTP/1.1 201 Created {"discount_code":{"id":1057371196,"price_rule_id":507328175,"code":"SUMMERSALE10OFF","usage_count":0,"created_at":"2025-01-02T11:31:50-05:00","updated_at":"2025-01-02T11:31:50-05:00"}} ``` ## Retrieves a list of discount codes

Retrieve a list of discount codes. Note: This endpoint implements pagination by using links that are provided in the response header. To learn more, refer to Make paginated requests to the REST Admin API.

The price_rule_id path parameter is the ID of the price rule that the discount codes belongs to.

### Endpoint /admin/api/#{api_version}/price_rules/{price_rule_id}/discount_codes.json (GET) ### Parameters * api_version (required): * price_rule_id (required): ### Responses #### 200 Retrieves a list of discount codes Examples: ##### Retrieve a list of all discount codes Request: ``` GET /admin/api/unstable/price_rules/507328175/discount_codes.json ``` Response: ``` HTTP/1.1 200 OK {"discount_codes":[{"id":507328175,"price_rule_id":507328175,"code":"SUMMERSALE10OFF","usage_count":0,"created_at":"2025-01-02T11:29:59-05:00","updated_at":"2025-01-02T11:29:59-05:00"}]} ``` ## Updates an existing discount code

Updates an existing discount code.

The price_rule_id path parameter is the ID of the price rule that the discount code belongs to. This is required because each discount code must belong to a price rule.

The discount_code_id path parameter is the ID of the discount code to update for the associated price rule.

### Endpoint /admin/api/#{api_version}/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json (PUT) ### Parameters * api_version (required): * discount_code_id (required): * price_rule_id (required): ### Responses #### 200 Updates an existing discount code Examples: ##### Update the code for a discount Request: ``` PUT /admin/api/unstable/price_rules/507328175/discount_codes/507328175.json {"discount_code":{"id":507328175,"code":"WINTERSALE20OFF"}} ``` Response: ``` HTTP/1.1 200 OK {"discount_code":{"id":507328175,"price_rule_id":507328175,"code":"WINTERSALE20OFF","usage_count":0,"created_at":"2025-01-02T11:29:59-05:00","updated_at":"2025-01-02T11:31:48-05:00"}} ``` ## Retrieves a single discount code

Retrieves a single discount code.

The price_rule_id path parameter is the ID of the price rule that the discount code belongs to. This is required because each discount code must belong to a price rule.

The discount_code_id path parameter is the ID of the discount code to retrieve for the associated price rule.

### Endpoint /admin/api/#{api_version}/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json (GET) ### Parameters * api_version (required): * discount_code_id (required): * price_rule_id (required): ### Responses #### 200 Retrieves a single discount code Examples: ##### Retrieve a single discount code Request: ``` GET /admin/api/unstable/price_rules/507328175/discount_codes/507328175.json ``` Response: ``` HTTP/1.1 200 OK {"discount_code":{"id":507328175,"price_rule_id":507328175,"code":"SUMMERSALE10OFF","usage_count":0,"created_at":"2025-01-02T11:29:59-05:00","updated_at":"2025-01-02T11:29:59-05:00"}} ``` ## Deletes a discount code

Deletes a discount code.

The price_rule_id path parameter is the ID of the price rule that the discount code belongs to. This is required because each discount code must belong to a price rule.

The discount_code_id path parameter is the ID of the discount code to delete for the associated price rule.

### Endpoint /admin/api/#{api_version}/price_rules/{price_rule_id}/discount_codes/{discount_code_id}.json (DELETE) ### Parameters * api_version (required): * discount_code_id (required): * price_rule_id (required): ### Responses #### 204 Deletes a discount code Examples: ##### Delete a discount code Request: ``` DELETE /admin/api/unstable/price_rules/507328175/discount_codes/507328175.json ``` Response: ``` HTTP/1.1 204 No Content ``` ## Retrieves the location of a discount code

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.

### Endpoint /admin/api/#{api_version}/discount_codes/lookup.json?code=SUMMERSALE10OFF (GET) ### Parameters * api_version (required): * code (required): Retrieves the location of a discount code by code name. ### Responses #### 303 Retrieves the location of a discount code Examples: ##### Search for a discount code Request: ``` GET /admin/api/unstable/discount_codes/lookup.json ``` Response: ``` HTTP/1.1 303 See Other ``` ## Retrieves a count of discount codes for a shop Retrieves a count of discount codes for a shop ### Endpoint /admin/api/#{api_version}/discount_codes/count.json (GET) ### Parameters * api_version (required): * times_used: Show discount codes with times used. * times_used_max: Show discount codes used greater than or equal to this value. * times_used_min: Show discount codes used less than or equal to this value. ### Responses #### 200 Retrieves a count of discount codes for a shop Examples: ##### Retrieve a count of discount codes for a shop Request: ``` GET /admin/api/unstable/discount_codes/count.json ``` Response: ``` HTTP/1.1 200 OK {"count":2} ``` ## Creates a discount code creation job

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. You can enqueue a single creation job per a shop and you can't enqueue more until the job completes.

The price_rule_id path parameter is the ID of the price rule that the discount code will belong to. This is required because each discount code must belong to a price rule.

Response fields that are specific to the batch endpoint include:

### Endpoint /admin/api/#{api_version}/price_rules/{price_rule_id}/batch.json (POST) ### Parameters * api_version (required): * price_rule_id (required): ### Responses #### 201 Creates a discount code creation job Examples: ##### Create a discount code creation job Request: ``` POST /admin/api/unstable/price_rules/507328175/batch.json {"discount_codes":[{"code":"SUMMER1"},{"code":"SUMMER2"},{"code":"SUMMER3"}]} ``` Response: ``` HTTP/1.1 201 Created {"discount_code_creation":{"id":989355119,"price_rule_id":507328175,"started_at":null,"completed_at":null,"created_at":"2025-01-02T11:31:50-05:00","updated_at":"2025-01-02T11:31:50-05:00","status":"queued","codes_count":3,"imported_count":0,"failed_count":0,"logs":[]}} ``` ## Retrieves a discount code creation job

Retrieves a discount code creation job

The price_rule_id path parameter is the ID of the price rule that the discount code creation job was ran for. This is required because each discount code creation job is associated to a price rule.

The batch_id path parameter is the ID of the discount code creation job for the associated price rule.

### Endpoint /admin/api/#{api_version}/price_rules/{price_rule_id}/batch/{batch_id}.json (GET) ### Parameters * api_version (required): * batch_id (required): * price_rule_id (required): ### Responses #### 200 Retrieves a discount code creation job Examples: ##### Retrieve a discount code creation job Request: ``` GET /admin/api/unstable/price_rules/507328175/batch/173232803.json ``` Response: ``` HTTP/1.1 200 OK {"discount_code_creation":{"id":173232803,"price_rule_id":507328175,"started_at":null,"completed_at":null,"created_at":"2025-01-02T11:29:59-05:00","updated_at":"2025-01-02T11:29:59-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

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

The price_rule_id path parameter is the ID of the price rule that the discount code creation job was ran for. This is required because each discount code creation job is associated to a price rule.

The batch_id path parameter is the ID of the discount code creation job for the associated price rule.

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.

### Endpoint /admin/api/#{api_version}/price_rules/{price_rule_id}/batch/{batch_id}/discount_codes.json (GET) ### Parameters * api_version (required): * batch_id (required): * price_rule_id (required): ### Responses #### 200 Retrieves a list of discount codes for a discount code creation job Examples: ##### Retrieve a list of discount codes for a discount code creation job Request: ``` GET /admin/api/unstable/price_rules/507328175/batch/173232803/discount_codes.json ``` Response: ``` HTTP/1.1 200 OK {"discount_codes":[{"id":null,"code":"foo","errors":{}},{"id":null,"code":"","errors":{}},{"id":null,"code":"bar","errors":{}}]} ```