Variants

In Lemon Squeezy, a product can have one or more variants. A variant represents a different option that is presented to the customer at checkout and has its own unique set of pricing options, files and license key settings.

A product will always have at least one variant. If only one variant exists for a product, it is considered the “default” variant and is not shown as a separate option at checkout. It will also have a pending status.


The variant object

Attributes


product_id

The ID of the product this variant belongs to.


name

The name of the variant.


slug

The slug used to identify the variant.


description

The description of the variant in HTML.


price

A positive integer in cents representing the price of the variant.


is_subscription

Has the value true if this variant is a subscription


interval

If this variant is a subscription, this is the frequency at which a subscription is billed. One of day, week, month or year.


interval_count

If this variant is a subscription, this is the number of intervals (specified in the interval attribute) between subscription billings. For example, interval=month and interval_count=3 bills every 3 months.


has_free_trial

Has the value true if this variant has a free trial period. Only available if the variant is a subscription.


trial_interval

The interval unit of the free trial. One of day, week, month or year.


trial_interval_count

If interval count of the free trial. For example, a variant with trial_interval=day and trial_interval_count=14 would have a free trial that lasts 14 days.


pay_what_you_want

Has the value true if this is a “pay what you want” variant where the price can be set by the customer at checkout.


min_price

If pay_what_you_want is true, this is the minimum price this variant can be purchased for, as a positive integer in cents


suggested_price

If pay_what_you_want is true, this is the suggested price for this variant shown at checkout, as a positive integer in cents


has_license_keys

Has the value true if this variant should generate license keys for the customer on purchase.


license_activation_limit

The maximum number of times a license key can be activated for this variant.


is_license_limit_unlimited

Has the value true if license key activations are unlimited for this variant.


license_length_value

The number of units (specified in the license_length_unit attribute) until a license key expires.


license_length_unit

The unit linked with the license_length_value attribute. One of days, months or years. For example, license_length_value=3 and license_length_unit=months license keys will expire after 3 months.


is_license_length_unlimited

Has the value true if license keys should never expire.

Note: If the variant is a subscription, the license key expiration will be linked to the status of the subscription (e.g. the license will expire when the subscription expires).


sort

An integer representing the order of this variant when displayed on the checkout.


status

The status of the variant. Either pending, draft or published. If a variant has a pending status, it is considered the “default” variant and is not shown as a separate option at checkout.


status_formatted

The formatted status of the variant.


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.

Variant object

{ "type": "variants", "id": "1", "attributes": { "product_id": 1, "name": "Example Variant", "slug": "46beb127-a8a9-33e6-89b5-078505657239", "description": "

Lorem ipsum...

", "price": 999, "is_subscription": false, "interval": null, "interval_count": null, "has_free_trial": false, "trial_interval": "day", "trial_interval_count": 30, "pay_what_you_want": false, "min_price": 0, "suggested_price": 0, "has_license_keys": false, "license_activation_limit": 5, "is_license_limit_unlimited": false, "license_length_value": 1, "license_length_unit": "years", "is_license_length_unlimited": false, "sort": 1, "status": "published", "status_formatted": "Published", "created_at": "2021-05-24T14:15:06.000000Z", "updated_at": "2021-06-24T14:44:38.000000Z" } }

Retrieve a variant

Retrieves the variant with the given ID.

GET /v1/variants/:id

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

Returns

Returns a variant object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/variants/1" }, "data": { "type": "variants", "id": "1", "attributes": { "product_id": 1, "name": "Example Variant", "slug": "46beb127-a8a9-33e6-89b5-078505657239", "description": "

Lorem ipsum...

", "price": 999, "is_subscription": false, "interval": null, "interval_count": null, "has_free_trial": false, "trial_interval": "day", "trial_interval_count": 30, "pay_what_you_want": false, "min_price": 0, "suggested_price": 0, "has_license_keys": false, "license_activation_limit": 5, "is_license_limit_unlimited": false, "license_length_value": 1, "license_length_unit": "years", "is_license_length_unlimited": false, "sort": 1, "status": "published", "status_formatted": "Published", "created_at": "2021-05-24T14:15:06.000000Z", "updated_at": "2021-06-24T14:44:38.000000Z" }, "relationships": { "product": { "links": { "related": "https://api.lemonsqueezy.com/v1/variants/1/product", "self": "https://api.lemonsqueezy.com/v1/variants/1/relationships/product" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/variants/1" } } }

List all variants

Returns a paginated list of variants.

Parameters


product_id

Only return variants belonging to the product with this ID.

GET /v1/variants

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

Returns

Returns a paginated list of variant objects ordered by sort.

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\/variants?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=sort", "last": "https:\/\/api.lemonsqueezy.com\/v1\/variants?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=sort", }, "data": [ { "type": "variants", "id": "1", "attributes": { "product_id": 1, "name": "Example Variant", "slug": "46beb127-a8a9-33e6-89b5-078505657239", "description": "

Lorem ipsum...<\/p>" "price": 999, "is_subscription": false, "interval": null, "interval_count": null, "has_free_trial": false, "trial_interval": "day", "trial_interval_count": 30, "pay_what_you_want": false, "min_price": 0, "suggested_price": 0, "has_license_keys": false, "license_activation_limit": 5, "is_license_limit_unlimited": false, "license_length_value": 1, "license_length_unit": "years", "is_license_length_unlimited": false, "sort": 1, "status": "published", "status_formatted": "Published", "created_at": "2021-05-24T14:15:06.000000Z", "updated_at": "2021-06-24T14:44:38.000000Z" }, "relationships": { "product": { "links": { "related": "https:\/\/api.lemonsqueezy.com\/v1\/variants\/1\/product", "self": "https:\/\/api.lemonsqueezy.com\/v1\/variants\/1\/relationships\/product" } } }, "links": { "self": "https:\/\/api.lemonsqueezy.com\/v1\/variants\/1" } }, {...}, {...}, ] }