Sign inGet started →
Help DocsAPI Guides

Orders

In Lemon Squeezy, an order is created when a customer purchases a product.

An order belongs to a Store, is associated with a Customer and can have many Order Items, Subscriptions, License Keys and Discount Redemptions.

The order object

Attributes

store_id

The ID of the store this order belongs to.

customer_id

The ID of the customer this order belongs to.

identifier

The unique identifier (UUID) for this order.

order_number

An integer representing the sequential order number for this store.

user_name

The full name of the customer.

user_email

The email address of the customer.

currency

The ISO 4217 currency code for the order (e.g. USD, GBP, etc).

currency_rate

If the order currency is USD, this will always be 1.0. Otherwise, this is the currency conversion rate used to determine the cost of the order in USD at the time of purchase.

subtotal

A positive integer in cents representing the subtotal of the order in the order currency.

setup_fee

A positive integer in cents representing the setup fee of the order in the order currency.

discount_total

A positive integer in cents representing the total discount value applied to the order in the order currency.

tax

A positive integer in cents representing the tax applied to the order in the order currency.

total

A positive integer in cents representing the total cost of the order in the order currency.

refunded_amount

A positive integer in cents representing the refunded amount of the order in the order currency.

subtotal_usd

A positive integer in cents representing the subtotal of the order in USD.

setup_fee_usd

A positive integer in cents representing the setup fee of the order in USD.

discount_total_usd

A positive integer in cents representing the total discount value applied to the order in USD.

tax_usd

A positive integer in cents representing the tax applied to the order in USD.

total_usd

A positive integer in cents representing the total cost of the order in USD.

refunded_amount_usd

A positive integer in cents representing the refunded amount of the order in USD.

tax_name

The name of the tax rate (e.g. VAT, Sales Tax, etc) applied to the order. Will be null if no tax was applied.

tax_rate

If tax is applied to the order, this will be the rate of tax as a decimal percentage.

tax_inclusive

A boolean indicating if the order was created with tax inclusive or exclusive pricing.

status

The status of the order. One of

  • pending
  • failed
  • paid
  • refunded
  • partial_refund

status_formatted

The formatted status of the order.

refunded

Has the value true if the order has been fully refunded.

refunded_at

If the order has been fully refunded, this will be an ISO 8601 formatted date-time string indicating when the order was refunded.

subtotal_formatted

A human-readable string representing the subtotal of the order in the order currency (e.g. $9.99).

setup_fee_formatted

A human-readable string representing the setup fee of the order in the order currency (e.g. $9.99).

discount_total_formatted

A human-readable string representing the total discount value applied to the order in the order currency (e.g. $9.99).

tax_formatted

A human-readable string representing the tax applied to the order in the order currency (e.g. $9.99).

total_formatted

A human-readable string representing the total cost of the order in the order currency (e.g. $9.99).

refunded_amount_formatted

A human-readable string representing the refunded amount of the order in the order currency (e.g. $9.99).

first_order_item

An object representing the first order item belonging to this order.

  • id - The ID of the order item.
  • order_id - The ID of the order.
  • product_id - The ID of the product.
  • variant_id - The ID of the product variant.
  • product_name - The name of the product.
  • variant_name - The name of the product variant.
  • price - A positive integer in cents representing the price of the order item in the order currency.
  • created_at - An ISO 8601 formatted date-time string indicating when the order item was created.
  • updated_at - An ISO 8601 formatted date-time string indicating when the order item was last updated.
  • test_mode - A boolean indicating if the order was made in test mode.

urls

An object of customer-facing URLs for this order. It contains:

  • receipt - A pre-signed URL for viewing the order in the customer's My Orders page.

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.

Order object

{ "type": "orders", "id": "1", "attributes": { "store_id": 1, "customer_id": 1, "identifier": "104e18a2-d755-4d4b-80c4-a6c1dcbe1c10", "order_number": 1, "user_name": "Darlene Daugherty", "user_email": "[email protected]", "currency": "USD", "currency_rate": "1.0000", "subtotal": 999, "setup_fee": 999, "discount_total": 0, "tax": 200, "total": 1199, "refunded_amount": 0, "subtotal_usd": 999, "setup_fee_usd": 999, "discount_total_usd": 0, "tax_usd": 200, "total_usd": 1199, "refunded_amount_usd": 0, "tax_name": "VAT", "tax_rate": "20.00", "tax_inclusive": false, "status": "paid", "status_formatted": "Paid", "refunded": false, "refunded_at": null, "subtotal_formatted": "$9.99", "setup_fee_formatted": "$9.99", "discount_total_formatted": "$0.00", "tax_formatted": "$2.00", "total_formatted": "$11.99", "refunded_amount_formatted": "$0.00", "first_order_item": { "id": 1, "order_id": 1, "product_id": 1, "variant_id": 1, "product_name": "Test Limited License for 2 years", "variant_name": "Default", "price": 1199, "created_at": "2021-08-17T09:45:53.000000Z", "updated_at": "2021-08-17T09:45:53.000000Z", "test_mode": false }, "urls": { "receipt": "https://app.lemonsqueezy.com/my-orders/104e18a2-d755-4d4b-80c4-a6c1dcbe1c10?signature=8847fff02e1bfb0c7c43ff1cdf1b1657a8eed2029413692663b86859208c9f42" }, "created_at": "2021-08-17T09:45:53.000000Z", "updated_at": "2021-08-17T09:45:53.000000Z", "test_mode": false } }

Retrieve an order

Retrieves the order with the given ID.

GET /v1/orders/:id

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

Returns

Returns an order object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/orders/1" }, "data": { "type": "orders", "id": "1", "attributes": { "store_id": 1, "customer_id": 1, "identifier": "104e18a2-d755-4d4b-80c4-a6c1dcbe1c10", "order_number": 1, "user_name": "Darlene Daugherty", "user_email": "[email protected]", "currency": "USD", "currency_rate": "1.0000", "subtotal": 999, "setup_fee": 999, "discount_total": 0, "tax": 200, "total": 1199, "refunded_amount": 0, "subtotal_usd": 999, "setup_fee_usd": 999, "discount_total_usd": 0, "tax_usd": 200, "total_usd": 1199, "refunded_amount_usd": 0, "tax_name": "VAT", "tax_rate": "20.00", "tax_inclusive": false, "status": "paid", "status_formatted": "Paid", "refunded": false, "refunded_at": null, "subtotal_formatted": "$9.99", "setup_fee_formatted": "$9.99", "discount_total_formatted": "$0.00", "tax_formatted": "$2.00", "total_formatted": "$11.99", "refunded_amount_formatted": "$0.00", "first_order_item": { "id": 1, "order_id": 1, "product_id": 1, "variant_id": 1, "product_name": "Test Limited License for 2 years", "variant_name": "Default", "price": 1199, "created_at": "2021-08-17T09:45:53.000000Z", "updated_at": "2021-08-17T09:45:53.000000Z", "deleted_at": null, "test_mode": false }, "urls": { "receipt": "https://app.lemonsqueezy.com/my-orders/104e18a2-d755-4d4b-80c4-a6c1dcbe1c10?signature=8847fff02e1bfb0c7c43ff1cdf1b1657a8eed2029413692663b86859208c9f42" }, "created_at": "2021-08-17T09:45:53.000000Z", "updated_at": "2021-08-17T09:45:53.000000Z", "test_mode": false }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/store", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/store" } }, "customer": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/customer", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/customer" } }, "order-items": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/order-items", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/order-items" } }, "subscriptions": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/subscriptions", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/subscriptions" } }, "license-keys": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/license-keys", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/license-keys" } }, "discount-redemptions": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/discount-redemptions", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/discount-redemptions" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/orders/1" } } }

List all orders

Returns a paginated list of orders.

Parameters

store_id

Only return orders belonging to the store with this ID.

user_email

Only return orders where the user_email field is equal to this email address.

GET /v1/orders

curl "https://api.lemonsqueezy.com/v1/orders" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'
curl "https://api.lemonsqueezy.com/v1/orders?filter[user_email][email protected]" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'

Returns

Returns a paginated list of order 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/orders?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-createdAt", "last": "https://api.lemonsqueezy.com/v1/orders?page%5Bnumber%5D=1&page%5Bsize%5D=10&sort=-createdAt" }, "data": [ { "type": "orders", "id": "1", "attributes": { "store_id": 1, "customer_id": 1, "identifier": "104e18a2-d755-4d4b-80c4-a6c1dcbe1c10", "order_number": 1, "user_name": "Darlene Daugherty", "user_email": "[email protected]", "currency": "USD", "currency_rate": "1.0000", "subtotal": 999, "setup_fee": 999, "discount_total": 0, "tax": 200, "total": 1199, "refunded_amount": 0, "subtotal_usd": 999, "setup_fee_usd": 999, "discount_total_usd": 0, "tax_usd": 200, "total_usd": 1199, "refunded_amount_usd": 0, "tax_name": "VAT", "tax_rate": "20.00", "tax_inclusive": false, "status": "paid", "status_formatted": "Paid", "refunded": false, "refunded_at": null, "subtotal_formatted": "$9.99", "setup_fee_formatted": "$9.99", "discount_total_formatted": "$0.00", "tax_formatted": "$2.00", "total_formatted": "$11.99", "refunded_amount_formatted": "$0.00", "first_order_item": { "id": 1, "order_id": 1, "product_id": 1, "variant_id": 1, "product_name": "Test Limited License for 2 years", "variant_name": "Default", "price": 1199, "created_at": "2021-08-17T09:45:53.000000Z", "updated_at": "2021-08-17T09:45:53.000000Z", "deleted_at": null, "test_mode": false }, "urls": { "receipt": "https://app.lemonsqueezy.com/my-orders/104e18a2-d755-4d4b-80c4-a6c1dcbe1c10?signature=8847fff02e1bfb0c7c43ff1cdf1b1657a8eed2029413692663b86859208c9f42" }, "created_at": "2021-08-17T09:45:53.000000Z", "updated_at": "2021-08-17T09:45:53.000000Z", "test_mode": false }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/store", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/store" } }, "customer": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/customer", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/customer" } }, "order-items": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/order-items", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/order-items" } }, "subscriptions": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/subscriptions", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/subscriptions" } }, "license-keys": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/license-keys", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/license-keys" } }, "discount-redemptions": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/discount-redemptions", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/discount-redemptions" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/orders/1" } }, {...}, {...}, ] }

Generate order invoice

Generates a new invoice for the given order with given parameters.

Attributes

name

Optional. The full name of the customer.

address

Optional. The street address of the customer.

city

Optional. The city of the customer.

state

Optional. The state of the customer.

zip_code

Optional. The ZIP code of the customer.

country

Optional. The country of the customer.

notes

Optional. Any additional notes to include on the invoice.

POST /v1/orders/:id/generate-invoice

curl -X "POST" "https://api.lemonsqueezy.com/v1/orders/1/generate-invoice?name=John%20Doe&address=123%20Main%20St&city=Anytown&state=CA&zip_code=12345&country=US¬es=Thank%20you%20for%20your%20business" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}'

Returns

Returns a link to download the generated invoice.

Response

{ "jsonapi": { "version": "1.0" }, "meta": { "urls": { "download_invoice": "https://app.lemonsqueezy.com/my-orders/c1e4de31-b4cf-4668-a6fe-019d071d41ab/invoice/download?address=123%20Main%20St&city=Anytown&country=US&name=John%20Doe¬es=Thank%20you%20for%20your%20business&state=CA&zip_code=12345&signature=c21a17a13d9deeacc99ff52144a06b49df141af37dd668cc70a76bcc8022888e" } } }

Issue a refund

Issues a partial refund for an order.

Attributes

amount

Required. The amount that you want to refund for an order.

POST /v1/orders/:id/refund

curl -X "POST" "https://api.lemonsqueezy.com/v1/orders/1/refund" -H 'Accept: application/vnd.api+json' -H 'Content-Type: application/vnd.api+json' -H 'Authorization: Bearer {api_key}' -d $'{ "data": { "type": "orders", "id": "1", "attributes": { "amount": 100 } } }'

Returns

Returns an order object.

Response

{ "jsonapi": { "version": "1.0" }, "links": { "self": "https://api.lemonsqueezy.com/v1/orders/1" }, "data": { "type": "orders", "id": "1", "attributes": { "store_id": 1, "customer_id": 1, "identifier": "104e18a2-d755-4d4b-80c4-a6c1dcbe1c10", "order_number": 1, "user_name": "Darlene Daugherty", "user_email": "[email protected]", "currency": "USD", "currency_rate": "1.0000", "subtotal": 999, "setup_fee": 999, "discount_total": 0, "tax": 200, "total": 1199, "refunded_amount": 100, "subtotal_usd": 999, "setup_fee_usd": 999, "discount_total_usd": 0, "tax_usd": 200, "total_usd": 1199, "refunded_amount_usd": 100, "tax_name": "VAT", "tax_rate": "20.00", "tax_inclusive": false, "status": "paid", "status_formatted": "Paid", "refunded": false, "refunded_at": null, "subtotal_formatted": "$9.99", "setup_fee_formatted": "$9.99", "discount_total_formatted": "$0.00", "tax_formatted": "$2.00", "total_formatted": "$11.99", "refunded_amount_formatted": "$1.00", "first_order_item": { "id": 1, "order_id": 1, "product_id": 1, "variant_id": 1, "product_name": "Test Limited License for 2 years", "variant_name": "Default", "price": 1199, "created_at": "2021-08-17T09:45:53.000000Z", "updated_at": "2021-08-17T09:45:53.000000Z", "deleted_at": null, "test_mode": false }, "urls": { "receipt": "https://app.lemonsqueezy.com/my-orders/104e18a2-d755-4d4b-80c4-a6c1dcbe1c10?signature=8847fff02e1bfb0c7c43ff1cdf1b1657a8eed2029413692663b86859208c9f42" }, "created_at": "2021-08-17T09:45:53.000000Z", "updated_at": "2021-08-17T09:45:53.000000Z", "test_mode": false }, "relationships": { "store": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/store", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/store" } }, "customer": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/customer", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/customer" } }, "order-items": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/order-items", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/order-items" } }, "subscriptions": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/subscriptions", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/subscriptions" } }, "license-keys": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/license-keys", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/license-keys" } }, "discount-redemptions": { "links": { "related": "https://api.lemonsqueezy.com/v1/orders/1/discount-redemptions", "self": "https://api.lemonsqueezy.com/v1/orders/1/relationships/discount-redemptions" } } }, "links": { "self": "https://api.lemonsqueezy.com/v1/orders/1" } } }