Previewing Checkout Totals With the API

To enhance your customer experience, sometimes you might want to show the estimated total costs — including location-specific taxes, discounts, and tax ID validation, before they enter the checkout. With Lemon Squeezy, this can be easily achieved with a single API call.

Getting started

If you haven’t already, make sure to read our Developer guide for a comprehensive walkthrough of setting up a full integration, including creating products and syncing customer data.

Previewing a checkout using the API

Using the Lemon Squeezy API, you can create a checkout preview by sending a request to the “Create a checkout” endpoint with "preview": true included in the request’s attributes.

POST https://api.lemonsqueezy.com/v1/checkouts

{
  "data": {
    "type": "checkouts",
    "attributes": {
      "checkout_data": {
        "billing_address": {
          "country": "DE"
        },
        "tax_number": "DE 123456789",
        "discount_code": "SUMMER10"
      },
      "preview": true
    },
    "relationships": {
      "store": {
        "data": {
          "type": "stores",
          "id": "1"
        }
      },
      "variant": {
        "data": {
          "type": "variants",
          "id": "1"
        }
      }
    }
  }
}

Breakdown of the request

• billing_address: Specifies the customer’s billing country.
• tax_number: The customer’s tax ID, if applicable.
• discount_code: Any discount code the customer is using.
• preview: Set to true to indicate that this is a preview

This setup will provide a precise estimation of the customer’s payment based on their details.

Understanding the response

Upon sending the request, the API returns a response which includes the usual Checkout object, but with extra data in data.attributes.preview, which will look like this:

{
  ...
  "data": {
    "type": "checkouts",
    "id": "cb9beae2-a60c-4db1-b7c4-edf6b303628a",
    "attributes": {
      ...
      "preview": {
        "currency": "USD",
        "currency_rate": 1,
        "subtotal": 2400,
        "discount_total": 0,
        "tax": 456,
        "total": 2856,
        "subtotal_usd": 2400,
        "discount_total_usd": 0,
        "tax_usd": 456,
        "total_usd": 2856,
        "subtotal_formatted": "$24.00",
        "discount_total_formatted": "$0.00",
        "tax_formatted": "$4.56",
        "total_formatted": "$28.56"
      },
      ...
    },
    "relationships": {
      ...
    },
    "links": {
      ...
    }
  }
}

The preview object includes:

• currency: The currency of the transaction.
• subtotal: The subtotal amount before tax and discounts.
• discount_total: Any applied discount amount.
• tax: The total tax amount.
• total: The final total after taxes and discounts.
• formatted values: Each monetary value in a human-readable format.

Displaying the pricing information

You can use the formatted values from the preview object to display an estimated total in your application, providing transparency for your customers:

Subtotal: $24.00
Tax:      $4.56
Total:    $28.56