5 min read
Lemon Squeezy Custom Data: Tie Orders and Subscriptions to Campaigns
Custom checkout data can preserve that connection. Lemon Squeezy returns the custom values in webhook events for orders, subscriptions, and license keys. A durable identifier can therefore follow the customer from the first checkout into later subscription events.
· Grometrics Team
Lemon Squeezy records orders, subscriptions, refunds, and payment events. Campaign attribution requires one more connection: the payment record must point back to the visit that introduced the customer.
Custom checkout data can preserve that connection. Lemon Squeezy returns the custom values in webhook events for orders, subscriptions, and license keys. A durable identifier can therefore follow the customer from the first checkout into later subscription events.
Pass an identifier, not a pile of campaign fields
First, capture the acquisition context on your site. Store the source, medium, campaign, referring page, and landing page in your analytics system. Give that record an internal identifier.
Then pass only the identifier to Lemon Squeezy. A checkout URL can include custom data like this:
https://store.example.com/checkout/buy/example?checkout[custom][attribution_id]=attr_01JEXAMPLEIf you create the checkout through the Lemon Squeezy API, use checkout_data.custom instead.
The checkout URL approach is convenient, but query values are visible in the browser and may appear in logs. Never put secrets, payment details, or unnecessary personal information in custom checkout fields.
Read the identifier from verified webhooks
Lemon Squeezy includes custom checkout data under meta.custom_data in supported webhook events. Your webhook handler can use that value to find the acquisition record and attach the resulting revenue.
Always verify the webhook signature before trusting the body. A public endpoint can receive arbitrary requests. Signature validation confirms that the event came from Lemon Squeezy and that its content was not changed in transit.
The processing sequence should be:
- Receive the webhook body without changing it.
- Validate the signature with the configured signing secret.
- Reject an invalid signature.
- Read the event name and unique event data.
- Read
meta.custom_data.attribution_id. - Apply the revenue change to the matching acquisition record.
- Record that the event was processed.
The last step prevents duplicate revenue. Lemon Squeezy retries failed webhook deliveries. A safe handler should produce the same result if it sees the same event again.
Track the whole customer value, not only the order
An initial order answers which campaign produced a purchase. Subscription and refund events answer whether that purchase remained valuable.
Useful Lemon Squeezy events include:
order_createdfor an initial order.order_refundedwhen revenue is returned.subscription_createdfor a new subscription.subscription_payment_successfor successful recurring revenue.subscription_payment_failedfor payment risk.subscription_cancelledandsubscription_expiredfor churn.
Keep every event connected to the same customer and original attribution record. This lets you compare campaigns using net revenue and retention instead of the number of checkout completions.
Decide what happens when attribution is missing
Some payments will arrive without an attribution identifier. The customer may have used an old link, blocked storage, or entered checkout through another path.
Do not guess a source. Classify the payment as unattributed, keep the revenue in totals, and measure the unattributed share. A visible gap is more useful than false precision.
A growing unattributed share usually points to a broken handoff. Check every button and purchase path that can open Lemon Squeezy Checkout.
Test with simulated events and a real checkout path
Lemon Squeezy supports test mode and simulated webhook events. Use them to verify signature handling and event processing. Also complete a test checkout through the same page and button that customers use. This confirms that the attribution identifier reaches checkout before the webhook arrives.
Verify these outcomes:
- One order creates one attributed revenue event.
- A retry does not add the same revenue twice.
- A refund reduces attributed net revenue.
- A subscription payment remains linked to the original campaign.
- A missing identifier remains clearly unattributed.
Grometrics Lemon Squeezy analytics connects these payment events to acquisition context so campaign decisions reflect revenue that actually arrived.
Sources
CONNECT YOUR PAYMENTS
Grometrics works with Stripe, RevenueCat, Gumroad, Shopify, and more. 5-minute setup.
Connect payments →See the full page:
Lemon Squeezy analyticsRELATED POSTS