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 productdescription
- A custom description for the productmedia
- An array of image URLs to use as the product's mediaredirect_url
- A custom URL to redirect to after a successful purchasereceipt_button_text
- A custom text to use for the order receipt email buttonreceipt_link_url
- A custom URL to use for the order receipt email buttonreceipt_thank_you_note
- A custom thank you note to use for the order receipt emailenabled_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
- Iftrue
, show the checkout overlaymedia
- Iffalse
, hide the product medialogo
- Iffalse
, hide the store logodesc
- Iffalse
, hide the product descriptiondiscount
- Iffalse
, hide the discount code fieldsubscription_preview
- Iffalse
, hide the "You will be charged..." subscription preview textbackground_color
- A custom hex color to use for the background of the checkout page.headings_color
- A custom hex color to use for the headings on the checkout page.primary_text_color
- A custom hex color to use for the primary text on the checkout page.secondary_text_color
- A custom hex color to use for the secondary text on the checkout page.links_color
- A custom hex color to use for the links on the checkout page.borders_color
- A custom hex color to use for the borders on the checkout page.checkbox_color
- A custom hex color to use for the checkboxes on the checkout page.active_state_color
- A custom hex color to indicate an active state on the checkout page.button_color
- A custom hex color to use for the checkout button.button_text_color
- A custom hex color to use for the text within the checkout button.terms_privacy_color
- A custom hex color to use for the terms and privacy text on the checkout page.dark
(deprecated) - Iftrue
, use the dark theme. This has been deprecated in favour of the color options.
checkout_data
An object containing any prefill or custom data to be used in the checkout. Possible options include:
email
- A pre-filled email addressname
- A pre-filled namebilling_address.country
- A pre-filled billing address country in a ISO 3166-1 alpha-2 formatbilling_address.zip
- A pre-filled billing address zip/postal codetax_number
- A pre-filled tax numberdiscount_code
- A pre-filled discount codecustom
- An object containing any custom data to be passed to the checkoutvariant_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 be1.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
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 productdescription
- A custom description for the productmedia
- An array of image URLs to use as the product's mediaredirect_url
- A custom URL to redirect to after a successful purchasereceipt_button_text
- A custom text to use for the order receipt email buttonreceipt_link_url
- A custom URL to use for the order receipt email buttonreceipt_thank_you_note
- A custom thank you note to use for the order receipt emailenabled_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
- Iftrue
, show the checkout overlaymedia
- Iffalse
, hide the product medialogo
- Iffalse
, hide the store logodesc
- Iffalse
, hide the product descriptiondiscount
- Iffalse
, hide the discount code fieldskip_trial
- Iftrue
, remove the free trialsubscription_preview
- Iffalse
, hide the "You will be charged..." subscription preview textbackground_color
- A custom hex color to use for the background of the checkout page.headings_color
- A custom hex color to use for the headings on the checkout page.primary_text_color
- A custom hex color to use for the primary text on the checkout page.secondary_text_color
- A custom hex color to use for the secondary text on the checkout page.links_color
- A custom hex color to use for the links on the checkout page.borders_color
- A custom hex color to use for the borders on the checkout page.checkbox_color
- A custom hex color to use for the checkboxes on the checkout page.active_state_color
- A custom hex color to indicate an active state on the checkout page.button_color
- A custom hex color to use for the checkout button.button_text_color
- A custom hex color to use for the text within the checkout button.terms_privacy_color
- A custom hex color to use for the terms and privacy text on the checkout page.dark
(deprecated) - Iftrue
, use the dark theme. This has been deprecated in favour of the color options.
checkout_data
An object containing any prefill or custom data to be used in the checkout. Possible options include:
email
- A pre-filled email addressname
- A pre-filled namebilling_address.country
- A pre-filled billing address country in a ISO 3166-1 alpha-2 formatbilling_address.zip
- A pre-filled billing address zip/postal codetax_number
- A pre-filled tax numberdiscount_code
- A pre-filled discount codecustom
- An object containing any custom data to be passed to the checkoutvariant_quantities
- A list containing quantity data objects
custom
should be an object like this:
variant_quantities
should be a list of objects containing a variant ID and a quantity value (both integers):
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
Returns
Returns a checkout object.
Response
Retrieve a checkout
Retrieves the checkout with the given ID.
GET /v1/checkouts/:id
Returns
Returns a checkout object.
Response
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
Returns
Returns a paginated list of checkout objects ordered by created_at
(descending).