Sign inGet started →
Help DocsAPI Guides

Checkouts

In Lemon Squeezy, a checkout represents a custom checkout page. Checkouts can be used to customize the checkout experience for a specific variant/product without having to create a new product in the dashboard.

A checkout belongs to a Store and is associated with a Variant.

The checkout object

Attributes

store_id

The ID of the store this checkout belongs to.

variant_id

The ID of the variant associated with this checkout.

Note: by default, all variants of the related product will be shown in the checkout, with your selected variant highlighted. If you want hide to other variants, you can utilise the product_options.enabled_variants option to determine which variant(s) are displayed in the checkout.

custom_price

If the value is not null, this represents a positive integer in cents representing the custom price of the variant.

product_options

An object containing any overridden product options for this checkout. Possible options include:

  • name - A custom name for the product
  • description - A custom description for the product
  • media - An array of image URLs to use as the product's media
  • redirect_url - A custom URL to redirect to after a successful purchase
  • receipt_button_text - A custom text to use for the order receipt email button
  • receipt_link_url - A custom URL to use for the order receipt email button
  • receipt_thank_you_note - A custom thank you note to use for the order receipt email
  • enabled_variants - An array of variant IDs to enable for this checkout. If this is empty, all variants will be enabled.

checkout_options

An object containing checkout options for this checkout. Possible options include:

  • embed - If true, show the checkout overlay
  • media - If false, hide the product media
  • logo - If false, hide the store logo
  • desc - If false, hide the product description
  • discount - If false, hide the discount code field
  • dark - If true, use the dark theme
  • subscription_preview - If false, hide the "You will be charged..." subscription preview text
  • button_color - A custom hex color to use for the checkout button. Text within the button will be either white or dark depending on the brightness of your button colour.

checkout_data

An object containing any prefill or custom data to be used in the checkout. Possible options include:

  • email - A pre-filled email address
  • name - A pre-filled name
  • billing_address.country - A pre-filled billing address country in a ISO 3166-1 alpha-2 format
  • billing_address.zip - A pre-filled billing address zip/postal code
  • tax_number - A pre-filled tax number
  • discount_code - A pre-filled discount code
  • custom - An object containing any custom data to be passed to the checkout
  • variant_quantities - A list containing quantity data objects

preview

If preview is passed as true in the request, the Checkout object will contain a preview object. This contains pricing information for the checkout, including tax, any discount applied, and the total price.

The preview object is only available when the checkout is created.

Values returned:

  • currency - The ISO 4217 currency code of the store (e.g. USD, GBP, etc).
  • currency_rate - If the store currency is USD, this will always be 1.0. Otherwise, this is the currency conversion rate used to determine the price of the checkout in USD at the time of purchase.
  • subtotal - A positive integer in cents representing the subtotal of the checkout in the store currency.
  • discount_total - A positive integer in cents representing the total discount value applied to the checkout in the store currency.
  • tax - A positive integer in cents representing the tax applied to the checkout in the store currency.
  • total - A positive integer in cents representing the total price of the checkout in the store currency.
  • subtotal_usd - A positive integer in cents representing the subtotal of the checkout in USD.
  • discount_total_usd - A positive integer in cents representing the total discount value applied to the checkout in USD.
  • tax_usd - A positive integer in cents representing the tax applied to the checkout in USD.
  • total_usd - A positive integer in cents representing the total price of the checkout in USD.
  • subtotal_formatted - A human-readable string representing the subtotal of the checkout in the store currency (e.g. $9.99).
  • discount_total_formatted - A human-readable string representing the total discount value applied to the checkout in the store currency (e.g. $9.99).
  • tax_formatted - A human-readable string representing the tax applied to the checkout in the store currency (e.g. $9.99).
  • total_formatted - A human-readable string representing the total price of the checkout in the store currency (e.g. $9.99).

expires_at

An ISO 8601 formatted date-time string indicating when the checkout expires. Can be null if the checkout is perpetual.

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.

url

The unique URL to access the checkout. Note: for security reasons, download URLs are signed. If the checkout expires_at is set, the URL will expire after the specified time.

Checkout object

{ "type": "checkouts", "id": "edc0158c-794a-445d-bfad-24ab66baeb01", "attributes": { "store_id": 1, "variant_id": 1, "custom_price": null, "product_options": { "name": "", "description": "", "media": [], "redirect_url": "", "receipt_button_text": "", "receipt_link_url": "", "receipt_thank_you_note": "", "enabled_variants": [] }, "checkout_options": { "embed": false, "media": true, "logo": true, "desc": true, "discount": true, "dark": false, "subscription_preview": true, "button_color": "#7047EB" }, "checkout_data": { "email": "", "name": "", "billing_address": { "country": "", "zip": "" }, "tax_number": "", "discount_code": "", "custom": [], "variant_quantities": [] }, "preview": { "currency": "USD", "currency_rate": 1, "subtotal": 5000, "discount_total": 0, "tax": 0, "total": 5000, "subtotal_usd": 5000, "discount_total_usd": 0, "tax_usd": 0, "total_usd": 5000, "subtotal_formatted": "$50.00", "discount_total_formatted": "$50.00", "tax_formatted": "$0.00", "total_formatted": "$5.00" }, "expires_at": null, "created_at": "2022-10-14T10:59:00.000000Z", "updated_at": "2022-10-14T10:59:00.000000Z", "test_mode": false, "url": "https://my-store.lemonsqueezy.com/checkout/custom/edc0158c-794a-445d-bfad-24ab66baeb01?signature=5ad42361086c156d0976dce023536716ef114ac73163920526813d2a95e22453" } }

Create a checkout

Create a custom checkout. Use this endpoint to create a unique checkout URL for a specific variant.

Attributes

custom_price

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

Note: If the product purchased is a subscription, this custom price is used for all renewal payments. If the subscription's variant changes in the future (i.e. the customer is moved to a different subscription "tier") the new variant's price will be used from that moment forward.

product_options

An object containing any overridden product options for this checkout. Possible options include:

  • name - A custom name for the product
  • description - A custom description for the product
  • media - An array of image URLs to use as the product's media
  • redirect_url - A custom URL to redirect to after a successful purchase
  • receipt_button_text - A custom text to use for the order receipt email button
  • receipt_link_url - A custom URL to use for the order receipt email button
  • receipt_thank_you_note - A custom thank you note to use for the order receipt email
  • enabled_variants - An array of variant IDs to enable for this checkout. If this is empty, all variants will be enabled.

checkout_options

An object containing checkout options for this checkout. Possible options include:

  • embed - If true, show the checkout overlay
  • media - If false, hide the product media
  • logo - If false, hide the store logo
  • desc - If false, hide the product description
  • discount - If false, hide the discount code field
  • skip_trial - If true, remove the free trial
  • dark - If true, use the dark theme
  • subscription_preview - If false, hide the "You will be charged..." subscription preview text
  • button_color - A custom hex color to use for the checkout button

checkout_data

An object containing any prefill or custom data to be used in the checkout. Possible options include:

  • email - A pre-filled email address
  • name - A pre-filled name
  • billing_address.country - A pre-filled billing address country in a ISO 3166-1 alpha-2 format
  • billing_address.zip - A pre-filled billing address zip/postal code
  • tax_number - A pre-filled tax number
  • discount_code - A pre-filled discount code
  • custom - An object containing any custom data to be passed to the checkout
  • variant_quantities - A list containing quantity data objects

custom should be an object like this:

"custom": { "user_id": "123" }

variant_quantities should be a list of objects containing a variant ID and a quantity value (both integers):

"variant_quantities": [ { "variant_id": 123, "quantity": 3 } ]

preview

A boolean indicating whether to return a preview of the checkout. If true, the checkout will include a preview object with the checkout preview data.

test_mode

A boolean indicating whether the checkout should be created in test mode.

expires_at

An ISO 8601 formatted date-time string indicating when the checkout expires. Can be null if the checkout is perpetual.

Relationships

store

The store this checkout belongs to.

variant

The variant associated with this checkout.

Note: by default, all variants of the related product will be shown in the checkout, with your selected variant highlighted. If you want hide to other variants, you can utilise the product_options.enabled_variants option to determine which variant(s) are displayed in the checkout.

POST /v1/checkouts

curl -X "POST" "https://api.lemonsqueezy.com/v1/checkouts" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}' -d $'{ "data": { "type": "checkouts", "attributes": { "custom_price": 50000, "product_options": { "enabled_variants": [ 1 ] }, "checkout_options": { "button_color": "#2DD272" }, "checkout_data": { "discount_code": "10PERCENTOFF", "custom": { "user_id": 123 } }, "expires_at": "2022-10-30T15:20:06Z", "preview": true }, "relationships": { "store": { "data": { "type": "stores", "id": "1" } }, "variant": { "data": { "type": "variants", "id": "1" } } } } }'

Returns

Returns a checkout object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/checkouts/5e8b546c-c561-4a2c-a586-40c18bb2a195" }, "data": { "type": "checkouts", "id": "5e8b546c-c561-4a2c-a586-40c18bb2a195", "attributes": { "store_id": 1, "variant_id": 1, "custom_price": 50000, "product_options": { "name": "", "description": "", "media": [], "redirect_url": "", "receipt_button_text": "", "receipt_link_url": "", "receipt_thank_you_note": "", "enabled_variants": [ 1 ] }, "checkout_options": { "embed": false, "media": true, "logo": true, "desc": true, "discount": true, "skip_trial": false, "dark": false, "subscription_preview": true, "button_color": "#2DD272" }, "checkout_data": { "email": "", "name": "", "billing_address": [], "tax_number": "", "discount_code": "", "custom": [], "variant_quantities": [] }, "preview": { "currency": "USD", "currency_rate": 1, "subtotal": 5000, "discount_total": 0, "tax": 0, "total": 5000, "subtotal_usd": 5000, "discount_total_usd": 0, "tax_usd": 0, "total_usd": 5000, "subtotal_formatted": "$50.00", "discount_total_formatted": "$50.00", "tax_formatted": "$0.00", "total_formatted": "$5.00" }, "expires_at": "2022-10-30T15:20:06.000000Z", "created_at": "2022-10-14T13:03:37.000000Z", "updated_at": "2022-10-14T13:03:37.000000Z", "test_mode": false, "url": "https://my-store.lemonsqueezy.com/checkout/custom/5e8b546c-c561-4a2c-a586-40c18bb2a195?expires=1667143206&signature=8f7248ad2022ef1d4111752ae02d14f8d04332274861ca5c3589eb22b5086a5b" }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/checkouts/5e8b546c-c561-4a2c-a586-40c18bb2a195/store", "self": "https://api.lemonsqueezy.com/v1/checkouts/5e8b546c-c561-4a2c-a586-40c18bb2a195/relationships/store" } }, "variant": { "links": { "related": "https://api.lemonsqueezy.com/v1/checkouts/5e8b546c-c561-4a2c-a586-40c18bb2a195/variant", "self": "https://api.lemonsqueezy.com/v1/checkouts/5e8b546c-c561-4a2c-a586-40c18bb2a195/relationships/variant" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/checkouts/5e8b546c-c561-4a2c-a586-40c18bb2a195" } } }

Retrieve a checkout

Retrieves the checkout with the given ID.

GET /v1/checkouts/:id

curl "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'

Returns

Returns a checkout object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a" }, "data": { "type": "checkouts", "id": "ac470bd4-7c41-474d-b6cd-0f296f5be02a", "attributes": { "store_id": 1, "variant_id": 1, "custom_price": null, "product_options": { "name": "", "description": "", "media": [], "redirect_url": "", "receipt_button_text": "", "receipt_link_url": "", "receipt_thank_you_note": "", "enabled_variants": [] }, "checkout_options": { "embed": false, "media": true, "logo": true, "desc": true, "discount": true, "skip_trial": false, "dark": false, "subscription_preview": true, "button_color": "#7047EB" }, "checkout_data": { "email": "", "name": "", "billing_address": [], "tax_number": "", "discount_code": "", "custom": [], "variant_quantities": [] }, "expires_at": null, "created_at": "2022-10-14T12:36:27.000000Z", "updated_at": "2022-10-14T12:36:27.000000Z", "test_mode": false, "url": "https://my-store.lemonsqueezy.com/checkout/custom/ac470bd4-7c41-474d-b6cd-0f296f5be02a?signature=ee3fd20c5bac48fe5e976cb106e743bc3f6f330540f8003ab331d638e2ce3b8b" }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a/store", "self": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a/relationships/store" } }, "variant": { "links": { "related": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a/variant", "self": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a/relationships/variant" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a" } } }

List all checkouts

Returns a paginated list of checkouts.

Parameters

store_id

Only return checkouts belonging to the store with this ID.

variant_id

Only return checkouts belonging to the variant with this ID.

GET /v1/checkouts

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

Returns

Returns a paginated list of checkout objects ordered by created_at (descending).

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/checkouts?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-createdAt", "last": "https://api.lemonsqueezy.com/v1/checkouts?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-createdAt" }, "data": [ { "type": "checkouts", "id": "ac470bd4-7c41-474d-b6cd-0f296f5be02a", "attributes": { "store_id": 1, "variant_id": 1, "custom_price": null, "product_options": { "name": "", "description": "", "media": [], "redirect_url": "", "receipt_button_text": "", "receipt_link_url": "", "receipt_thank_you_note": "", "enabled_variants": [] }, "checkout_options": { "embed": false, "media": true, "logo": true, "desc": true, "discount": true, "skip_trial": true, "dark": false, "subscription_preview": true, "button_color": "#7047EB" }, "checkout_data": { "email": "", "name": "", "billing_address": [], "tax_number": "", "discount_code": "", "custom": [], "variant_quantities": [] }, "expires_at": null, "created_at": "2022-10-14T12:36:27.000000Z", "updated_at": "2022-10-14T12:36:27.000000Z", "test_mode": false, "url": "https://my-store.lemonsqueezy.com/checkout/custom/ac470bd4-7c41-474d-b6cd-0f296f5be02a?signature=ee3fd20c5bac48fe5e976cb106e743bc3f6f330540f8003ab331d638e2ce3b8b" }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a/store", "self": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a/relationships/store" } }, "variant": { "links": { "related": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a/variant", "self": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a/relationships/variant" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/checkouts/ac470bd4-7c41-474d-b6cd-0f296f5be02a" } }, {...}, {...}, ] }