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 dayweekmonth 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.

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 daysmonths 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 pendingdraft 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": "<p>Lorem ipsum...<\/p>",
    "price": 999,
    "is_subscription": 0,
    "interval": null,
    "interval_count": null,
    "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.

Returns

Returns a variant object.

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}'

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": "<p>Lorem ipsum...<\/p>",
      "price": 999,
      "is_subscription": 0,
      "interval": null,
      "interval_count": null,
      "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.

Returns

Returns a paginated list of variant objects ordered by sort.

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}'

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": "<p>Lorem ipsum...<\/p>"
        "price": 999,
        "is_subscription": 0,
        "interval": null,
        "interval_count": null,
        "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"
      }
    },
    {...},
    {...},
  ]
}