Passing Custom Data

For example, if you’re building a SaaS application and need to link a subscription with an existing user in your system, you may want to pass the user ID to the checkout. This ID will then be available in Order, Subscription and License key related webhook events making it easy to identify your local user when saving webhook data.

Passing custom data in checkout links

Passing custom data through the checkout works in the same way as prefilling checkout fields, by adding parameters to the checkout link:

https://[STORE].lemonsqueezy.com/checkout/buy/[VARIANT_ID]?checkout[custom][user_id]=123

You can add as many fields as you like using the checkout[custom] array, although we recommend restraint and try to only pass the minimal data required through the checkout.

https://[STORE].lemonsqueezy.com/checkout/buy/[VARIANT_ID]
?checkout[custom][user_id]=123
&checkout[custom][campaign_id]=abc

Passing custom data with the API

You can also pass custom data to checkout links created with the API by passing a JSON object inside checkout_data.custom. Read the API docs for more details.

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": {
      "checkout_data": {
        "custom": {
          "user_id": 123,
          "campaign_id": "abc"
        }
      }
    },
    "relationships": {
      "store": {
        "data": {
          "type": "stores",
          "id": "1"
        }
      },
      "variant": {
        "data": {
          "type": "variants",
          "id": "1"
        }
      }
    }
  }
}'

Access custom data in webhooks

If you passed custom data to a checkout (either with URL parameters or with the API) webhooks for Order, Subscription or License Key objects will contain a custom_data object inside the meta field:

{
  "meta": {
    "event_name": "order_created",
    "custom_data": {
      "user_id": "123",
      "campaign_id": "abc"
    }
  },
  ...
}

Read our API documentation on setting up webhooks in your application.