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.


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
  • 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

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.


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, "button_color": "#7047EB" }, "checkout_data": { "email": "", "name": "", "billing_address": { "country": "", "zip": "" }, "tax_number": "", "discount_code": "", "custom": [] }, "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.


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
  • 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

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.

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": 599, "product_options": { "enabled_variants": [ 1 ] }, "checkout_options": { "button_color": "#2DD272" } "expires_at": "2022-10-30T15:20:06Z" }, "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": 599, "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, "dark": false, "button_color": "#2DD272" }, "checkout_data": { "email": "", "name": "", "billing_address": [], "tax_number": "", "discount_code": "", "custom": [] }, "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, "dark": false, "button_color": "#7047EB" }, "checkout_data": { "email": "", "name": "", "billing_address": [], "tax_number": "", "discount_code": "", "custom": [] }, "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}'

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, "dark": false, "button_color": "#7047EB" }, "checkout_data": { "email": "", "name": "", "billing_address": [], "tax_number": "", "discount_code": "", "custom": [] }, "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" } }, {...}, {...}, ] }