Sign inGet started →
Help DocsAPI Guides

Discounts

In Lemon Squeezy, a discount contains information about a percentage or amount discount that can be applied to an order at checkout via a code.

A discount belongs to a Store and can have many Discount Redemptions.

The discount object

Attributes

store_id

The ID of the store this discount belongs to.

name

The name of the discount.

code

The discount code that can be used at checkout. Made up of uppercase letters and numbers and between 3 and 256 characters long.

amount

The amount of discount to apply to the order. Either a fixed amount in cents or a percentage depending on the value of amount_type.

amount_type

The type of the amount. Either percent or fixed.

is_limited_to_products

Has the value true if the discount can only be applied to certain products/variants.

is_limited_redemptions

Has the value true if the discount can only be redeemed a limited number of times.

max_redemptions

If is_limited_redemptions is true, this is the maximum number of redemptions.

starts_at

An ISO 8601 formatted date-time string indicating when the discount is valid from. Can be null if no start date is specified.

expires_at

An ISO 8601 formatted date-time string indicating when the discount expires. Can be null if no expiration date is specified.

duration

If the discount is applied to a subscription, this specifies how often the discount should be applied. One of

  • once - The discount will be applied to the initial payment only.
  • repeating - The discount will be applied to a certain number of payments (use in combination with duration_in_months.
  • forever - The discount will apply to all payments.

duration_in_months

If duration is repeating, this specifies how many months the discount should apply.

status

The status of the discount. Either draft or published.

status_formatted

The formatted status of the discount.

created_at

An ISO 8601 formatted date-time string indicating when the object was created.

updated_at

An ISO 8601 formatted date-time string indicating when the object was last updated.

test_mode

A boolean indicating if the object was created within test mode.

Discount object

{ "type": "discounts", "id": "1", "attributes": { "store_id": 1, "name": "10%", "code": "10PERC", "amount": 10, "amount_type": "percent", "is_limited_to_products": false, "is_limited_redemptions": false, "max_redemptions": 0, "starts_at": null, "expires_at": null, "duration": "once", "duration_in_months": 1, "status": "published", "status_formatted": "Published", "created_at": "2021-05-24T14:15:06.000000Z", "updated_at": "2021-05-24T14:15:06.000000Z", "test_mode": false } }

Create a discount

Create a discount.

Attributes

name

The name of the discount.

code

The discount code that can be used at checkout. Uppercase letters and numbers are allowed. Must be between 3 and 256 characters.

amount

The amount of discount to apply to the order. Either a fixed amount in cents or a percentage depending on the value of amount_type.

  • 1000 means $10 when amount_type is fixed.
  • 10 means 10% when amount_type is percent.

amount_type

The type of the amount. Either percent or fixed.

is_limited_to_products

Set this to true if the discount should only be applied to certain products/variants. See details in the Relationships section below.

is_limited_redemptions

Set this to true if the discount should only be redeemed a limited number of times. See max_redemptions below.

max_redemptions

If is_limited_redemptions is true, this is the maximum number of redemptions.

starts_at

An ISO 8601 formatted date-time string indicating when the discount is valid from. Can omitted or null if no start date is specified.

expires_at

An ISO 8601 formatted date-time string indicating when the discount expires. Can omitted or null if the discount is perpetual.

duration

If the discount is applied to a subscription, this specifies how often the discount should be applied. One of

  • once - The discount will be applied to the initial payment only.
  • repeating - The discount will be applied to a certain number of payments (use in combination with duration_in_months.
  • forever - The discount will apply to all payments.

Defaults to once if omitted.

duration_in_months

If duration is repeating, this specifies how many months the discount should apply. Defaults to 1 if omitted.

Note: for yearly subscription, the value needs to be years x 12, so 24 if you want the discount to repeat for the first two yearly payments. We do not recommend repeated discounts for daily or weekly subscriptions.

test_mode

Set this to true if the discount should only be applied to test mode orders.

Relationships

store

The store this discount belongs to.

variants

If is_limited_to_products is true, the variant(s) the discount belongs to (this is not required otherwise).

POST /v1/discounts

curl -X "POST" "https://api.lemonsqueezy.com/v1/discounts" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}' -d $'{ "data": { "type": "discounts", "attributes": { "name": "10% Off", "code": "10PERCENT", "amount": 10, "amount_type": "percent" }, "relationships": { "store": { "data": { "type": "stores", "id": "1" } } } } }'

An example limiting the discount to certain variants:

curl -X "POST" "https://api.lemonsqueezy.com/v1/discounts" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}' -d $'{ "data": { "type": "discounts", "attributes": { "name": "10% Off", "code": "10PERCENT", "amount": 10, "amount_type": "percent", "is_limited_to_products": true }, "relationships": { "store": { "data": { "type": "stores", "id": "1" } }, "variants": { "data": [ { "type": "variants", "id": "3" }, { "type": "variants", "id": "4" } ] } } } }'

Returns

Returns a discount object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/discounts/1" }, "data": { "type": "discounts", "id": "1", "attributes": { "store_id": 1, "name": "10% Off", "code": "10PERCENT", "amount": 10, "amount_type": "percent", "is_limited_to_products": false, "is_limited_redemptions": false, "max_redemptions": 0, "starts_at": null, "expires_at": null, "duration": "once", "duration_in_months": 1, "status": "published", "status_formatted": "Published", "created_at": "2021-05-24T14:15:06.000000Z", "updated_at": "2021-05-24T14:15:06.000000Z", "test_mode": false }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/discounts/1/store", "self": "https://api.lemonsqueezy.com/v1/discounts/1/relationships/store" } }, "variants": { "links": { "related": "https://api.lemonsqueezy.com/v1/discounts/1/variants", "self": "https://api.lemonsqueezy.com/v1/discounts/1/relationships/variants" } }, "discount-redemptions": { "links": { "related": "https://api.lemonsqueezy.com/v1/discounts/1/discount-redemptions", "self": "https://api.lemonsqueezy.com/v1/discounts/1/relationships/discount-redemptions" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/discounts/1" } } }

Retrieve a discount

Retrieves the discount with the given ID.

GET /v1/discounts/:id

curl "https://api.lemonsqueezy.com/v1/discounts/1" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'

Returns

Returns a discount object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/discounts/1" }, "data": { "type": "discounts", "id": "1", "attributes": { "store_id": 1, "name": "10%", "code": "10PERC", "amount": 10, "amount_type": "percent", "is_limited_to_products": false, "is_limited_redemptions": false, "max_redemptions": 0, "starts_at": null, "expires_at": null, "duration": "once", "duration_in_months": 1, "status": "published", "status_formatted": "Published", "created_at": "2021-05-24T14:15:06.000000Z", "updated_at": "2021-05-24T14:15:06.000000Z", "test_mode": false }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/discounts/1/store", "self": "https://api.lemonsqueezy.com/v1/discounts/1/relationships/store" } }, "variants": { "links": { "related": "https://api.lemonsqueezy.com/v1/discounts/1/variants", "self": "https://api.lemonsqueezy.com/v1/discounts/1/relationships/variants" } }, "discount-redemptions": { "links": { "related": "https://api.lemonsqueezy.com/v1/discounts/1/discount-redemptions", "self": "https://api.lemonsqueezy.com/v1/discounts/1/relationships/discount-redemptions" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/discounts/1" } } }

Delete a discount

Delete a discount with the given ID.

Returns

Returns a 204 No Content response on success.

DELETE /v1/discounts/:id

curl -X "DELETE" "https://api.lemonsqueezy.com/v1/discounts/1" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'

List all discounts

Returns a paginated list of discounts.

Parameters

store_id

Only return discounts belonging to the store with this ID.

GET /v1/discounts

curl "https://api.lemonsqueezy.com/v1/discounts" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'
curl "https://api.lemonsqueezy.com/v1/discounts?filter[store_id]=11" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'

Returns

Returns a paginated list of discount objects ordered by created_at.

Response

{ "meta": { "page": { "currentPage": 1, "from": 1, "lastPage": 1, "perPage": 10, "to": 10, "total": 10 } }, "jsonapi": { "version": "1.0" }, "links": { "first": "https://api.lemonsqueezy.com/v1/discounts?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=createdAt", "last": "https://api.lemonsqueezy.com/v1/discounts?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=createdAt" }, "data": [ { "type": "discounts", "id": "1", "attributes": { "store_id": 1, "name": "10%", "code": "10PERC", "amount": 10, "amount_type": "percent", "is_limited_to_products": false, "is_limited_redemptions": false, "max_redemptions": 0, "starts_at": null, "expires_at": null, "duration": "once", "duration_in_months": 1, "status": "published", "status_formatted": "Published", "created_at": "2021-05-24T14:15:06.000000Z", "updated_at": "2021-05-24T14:15:06.000000Z", "test_mode": false }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/discounts/1/store", "self": "https://api.lemonsqueezy.com/v1/discounts/1/relationships/store" } }, "variants": { "links": { "related": "https://api.lemonsqueezy.com/v1/discounts/1/variants", "self": "https://api.lemonsqueezy.com/v1/discounts/1/relationships/variants" } }, "discount-redemptions": { "links": { "related": "https://api.lemonsqueezy.com/v1/discounts/1/discount-redemptions", "self": "https://api.lemonsqueezy.com/v1/discounts/1/relationships/discount-redemptions" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/discounts/1" } }, {...}, {...}, ] }

Create a discount

Create a new discount.

Attributes

name

The name of the discount.

code

The unique and alphanumeric code that can be used to redeem the discount.

amount

The discount amount. For example, 20 would be a 20% discount for a percent amount_type, and a $.20 discount for a fixed amount_type.

amount_type

The discount amount type. Can be either percent or fixed.

is_limited_to_products

Optional. Whether the discount is limited to specific products. If true, the discount can only be redeemed for the product's variants specified in the variants relationship.

is_limited_redemptions

Optional. Whether the discount is limited to a specific number of redemptions. If true, the discount can only be redeemed a maximum of max_redemptions times.

max_redemptions

Optional. The maximum number of times the discount can be redeemed. Only applicable if is_limited_redemptions is true.

starts_at

An ISO-8601 formatted date-time string indicating when the discount starts. If not set, the discount starts immediately.

expires_at

An ISO-8601 formatted date-time string indicating when the discount expires. If not set, the discount never expires.

duration

Optional. The duration of the discount. Can be either once, repeating, or forever. If once, the discount can only be redeemed once. If repeating, the discount can be redeemed every duration_in_months months.

duration_in_months

The number of months the discount is valid for. Only applicable if duration is repeating.

Relationships

store

The store this discount belongs to.

variants

The product variants this discount is limited to. Only applicable if is_limited_to_products is true.

POST /v1/discounts

curl -X "POST" "https://api.lemonsqueezy.com/v1/discounts" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}' -d $'{ "data": { "type": "discounts", "attributes": { "name": "Custom Discount", "code": "CUSTOM20", "amount": 20, "amount_type": "percent", "starts_at": "2023-01-03T15:28:27.000000Z", "expires_at": "2023-04-03T15:28:27.000000Z", "is_limited_to_products": true }, "relationships": { "store": { "data": { "type": "stores", "id": "1" } }, "variants": { "data": [ { "type": "variants", "id": "1" }, { "type": "variants", "id": "2" } ] } } } }'

Returns

Returns the newly created discount object.

Discount object

{ "type": "discounts", "id": "1", "attributes": { "store_id": 1, "name": "Custom Discount", "code": "CUSTOM20", "amount": 20, "amount_type": "percent", "is_limited_to_products": true, "is_limited_redemptions": null, "max_redemptions": null, "starts_at": "2023-01-03T15:28:27.000000Z", "expires_at": "2023-04-03T15:28:27.000000Z", "duration": null, "duration_in_months": null, "status": null, "status_formatted": "", "created_at": "2023-01-04T18:16:17.000000Z", "updated_at": "2023-01-04T18:16:17.000000Z", "test_mode": false } }

Delete a discount

Delete an existing discount code.

DELETE /v1/discounts/{id}

curl -X "DELETE" "https://api.lemonsqueezy.com/v1/discounts/{id}" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'

Returns

Returns a 204 No Content response if the discount was successfully deleted.