Lemon Squeezy

What this lets you do

Connect Lemon Squeezy to Traceten and see which AI sources drive paying customers, not just pageviews. When an order is paid, Traceten matches it back to the originating session and attributes the revenue to the correct AI source.

Before you start

A Traceten account with at least one site tracked.
A Lemon Squeezy account, and permission to create API keys on it.
Your Lemon Squeezy store ID. It is the number in your store settings.
The Traceten snippet installed and verified on the site your checkout runs from.
Workspace admin in Traceten. Connecting and disconnecting a revenue source affects the whole workspace, so only admins can do it.

Connect Lemon Squeezy

You connect by pasting an API key and your store ID. There is no OAuth redirect, and there is no webhook to configure: Traceten creates the webhook on your Lemon Squeezy account for you.

Create an API key in Lemon Squeezy

Open Lemon Squeezy → Settings → API and click + to create a key.Give it a name (for example, Traceten) and copy it. Lemon Squeezy shows the key once.

Find your store ID

Open Settings → Stores and select the store whose revenue you want to attribute. The store ID is the number shown there.Traceten asks for it because a Lemon Squeezy API key covers every store on your account. Without the store ID, Traceten cannot tell which store this site sells through.

Paste both into Traceten

Go to app.traceten.com/dashboard, open Settings → Integrations, and choose the site your checkout runs from at the top of the page.Pick Lemon Squeezy from the list of payment providers, then paste the API key and the store ID.Click Connect.

Confirm the connection

Lemon Squeezy shows as Connected, with your store name, its currency, and the last four characters of the key.Traceten stores the key encrypted. After this point it is never shown again, in the dashboard or in the API, and only those last four characters are readable back.

What Traceten does with the key

In the same request, Traceten:

Reads the store’s name and currency, to confirm the key can see the store you named.
Reads one order, to prove the key can actually see the revenue it is being connected for.
Creates a webhook on your Lemon Squeezy account pointed at Traceten, subscribed to two events.
Stores the key and the webhook signing secret, both encrypted.
Starts importing your last 90 days of paid orders.

You can see the webhook Traceten created under Settings → Webhooks. These are the two events:

Event	What Traceten does with it
`order_created`	Attributes the order. This is the revenue.
`order_refunded`	Subtracts the refunded amount from the source that earned it.

order_created carries every payment, renewals included, because a Lemon Squeezy subscription renewal creates a new order. Every renewal is attributed to the AI source that won the customer, exactly like a first purchase. That is also why Traceten subscribes to neither subscription_payment_success nor any subscription_* event: the money is already on the order, and taking it from both places would count it twice. One limit worth knowing: a Lemon Squeezy order does not say which subscription it belongs to, so Lemon Squeezy renewals appear in your revenue totals and per-source breakdowns but not in the per-subscription lifetime value report.

The signing secret

Traceten generates the webhook signing secret and sends it to Lemon Squeezy when it creates the webhook. Lemon Squeezy never returns a webhook secret through its API, so the copy Traceten stores is the only one it will ever have. If that store fails for any reason, Traceten deletes the webhook it just created rather than leaving one behind that it could never verify. If you rotate the secret by hand in the Lemon Squeezy dashboard, Traceten stops accepting deliveries. Reconnect from the Traceten dashboard to provision a fresh one.

Keys Traceten will not accept

Stripe keys. Pasting one names the mistake rather than failing on a network call.
A key with no store ID. The connect form asks for both, and refuses with an explanation rather than guessing at a store.
A key with whitespace or a line break in it. Copy it again from Settings → API.

How attribution works

When an order is paid, Lemon Squeezy sends an order_created webhook to Traceten. Traceten then tries to tie the payment back to the originating session, in priority order:

Checkout custom data: if you passed the visitor’s _traceten_vid cookie as traceten_visitor_id, Traceten matches it to the originating session exactly.
Confirmation modal button: if you added ?order_identifier=[order_identifier] to the confirmation modal’s button link and the buyer clicks it, the Traceten snippet on that page reports the order identifier and Traceten matches it to the browser that completed the purchase. See below.
Email hash: if the buyer’s session called traceten.identify({ email }), Traceten matches the order’s email (hashed, never stored) to that visitor.
No match: the payment is still recorded so revenue totals stay complete, but it shows as unattributed (no AI source).

Orders with a status of pending, failed or refunded are not counted. A fully refunded order is skipped outright rather than counted and then taken back off, because there would be nothing to take it off with: the 90-day history import reads orders and never refunds, so importing one that was already refunded would add revenue that no later event ever removes. Only paid and partial_refund orders produce revenue. An order that was paid when Traceten recorded it and is refunded afterwards is a different case, and that one is reduced: see below.

Refunds and net revenue

Your attributed revenue is net of refunds. When an order_refunded event arrives, Traceten subtracts the refunded amount from the AI source the original order was attributed to.

The refund is dated on the day it was issued, not the day of the original order. A past day’s revenue figure never changes after the fact, and a day on which you refunded more than you took in reads as a negative number.
Conversion counts stay gross. A refunded order still counts as a conversion. The money is reported separately as a refunded figure beside the net one.
A partial refund subtracts only the part you returned. Lemon Squeezy reports refunded_amount as the running total refunded against the order, so a second partial refund subtracts only the difference rather than the whole new total. A partial_refund order keeps the share you kept.
A cancelled subscription is not a refund. Cancelling stops future charges. The charges already paid were earned and stay in your totals, so cancelling a subscription changes no figure in Traceten. Only an order_refunded takes money back off.

Traceten also ignores a delivery for an order created more than seven days ago. Lemon Squeezy’s signature carries no timestamp, so this is what stops an old delivery being replayed against your account; Lemon Squeezy’s own retries all happen well inside it.

Checkout overlay: attribute without writing code

A bare Lemon Squeezy checkout link or Buy Now button never goes through your server, so there is no place to attach custom data. Instead, have Lemon Squeezy hand the order identifier back to your own site, and let the snippet do the rest.

Connect Lemon Squeezy to Traceten

Follow the connection steps above. Traceten ignores a confirmation-page report for a site whose Lemon Squeezy store is not connected.

Open the product's confirmation modal settings

Lemon Squeezy dashboard, Products → your product → Edit → Confirmation modal.

Set the button link

Point it at a page on your site that has the Traceten snippet installed, and append the order_identifier parameter:

https://yourdomain.com/thanks?order_identifier=[order_identifier]

The square brackets are part of the syntax here, not a placeholder to fill in. Lemon Squeezy replaces [order_identifier] with the order’s unique identifier when it builds the button. Curly braces will not work.Use [order_identifier], not [order_id]. Traceten does not accept the numeric order id, because it counts up one order at a time and anyone could guess it.

Save, then buy something through the checkout

Complete a real purchase and click the button in the confirmation modal. The snippet reads order_identifier out of the URL, and the order appears against its AI source in Revenue, usually within a minute or two.

This is a button the buyer has to click, not an automatic redirect. Lemon Squeezy’s own docs say not to rely on the confirmation modal for order fulfilment for exactly this reason. Buyers who close the modal are never matched, so this path attributes a meaningful share of your Payment Link sales, not all of them. Checkout custom data, where you can use it, matches every order.

More things worth knowing:

You change nothing in your code. The only edit is the button link in Lemon Squeezy.
The order of events does not matter. Lemon Squeezy’s webhook usually reaches Traceten before the buyer clicks through. When that happens the order is recorded first and re-attributed the moment the browser reports in, on the original order’s own date.
The buyer has to click through within 30 minutes of paying. Traceten pairs a report with an order only when the two are no more than 30 minutes apart. A button clicked later than that is not matched, and the order stays as it was.
The page needs the snippet. If the button points somewhere the snippet is not installed, nothing is reported and the order stays unattributed.
Connecting comes first. Reports that arrive before your store is connected are discarded, not held until later. A report can also be discarded for up to a minute after you connect.

This path matches a browser, not a person. A confirmation link opened on a different device, or forwarded to somebody else, is not matched.

Passing the visitor ID through checkout

This is the most reliable attribution path, and the only one that works for a buyer who never identified themselves on your site. Pass the visitor’s pseudonymous Traceten identifier into the checkout as custom data.

In the dashboard, open Settings → Integrations, pick Lemon Squeezy and click Set up with AI. It copies a prompt for your coding assistant that wires the visitor ID into your checkout. The same card shows this site’s Visitor cookie name.

The robust way to get the value is window.traceten.getVisitorId(), called client-side and forwarded to whatever creates the checkout:

// Client-side: read the visitor id and send it to your own backend
const visitorId = window.traceten.getVisitorId(); // null before the first pageview resolves

If you’d rather not change your client-side request shape, read the cookie directly server-side instead:

Do not hardcode this cookie name. It is per-site and only correct on your configured domain (not on localhost). Find the real one under Sites → Settings → Cookies → Visitor cookie name.

// Server-side: create a Lemon Squeezy checkout
const visitorId = req.cookies["_traceten_vid"] ?? "";

await fetch("https://api.lemonsqueezy.com/v1/checkouts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LEMONSQUEEZY_API_KEY}`,
    "Content-Type": "application/vnd.api+json",
  },
  body: JSON.stringify({
    data: {
      type: "checkouts",
      attributes: {
        checkout_data: {
          custom: { traceten_visitor_id: visitorId },
        },
      },
      // ... your store and variant relationships
    },
  }),
});

Lemon Squeezy returns the value as meta.custom_data on the webhook, and Traceten matches it back to the AI session that produced the visit. No personal data leaves your server on this path: the cookie value is pseudonymous and is not PII. If you use a hosted Lemon Squeezy checkout link instead, append the value as a query parameter:

https://yourstore.lemonsqueezy.com/checkout/buy/VARIANT?checkout[custom][traceten_visitor_id]=VISITOR_ID

What the 90-day import can and cannot match

Traceten imports your last 90 days of paid orders when you connect, so revenue from before the webhook existed is not lost. It reads newest first and stops paging at the first order older than 90 days. Lemon Squeezy’s orders endpoint has no date filter, so one page (the one straddling that boundary) is retrieved and parsed in full, including the buyer email addresses on the orders that turn out to be older than 90 days. Those orders are discarded in memory: not imported, not stored, not logged. No page beyond the boundary is requested. Those historical orders match by email only. Lemon Squeezy’s orders API does not return checkout custom data, so the visitor ID path above applies to live orders only. An imported order whose buyer never called traceten.identify({ email }) lands as unattributed.

Verify it worked

Lemon Squeezy reads Connected in the dashboard.
The import banner finishes, and the Revenue page shows historical orders.
Place a real order (or a test-mode one in a non-production Traceten environment). It appears in Revenue within a minute or two.

Troubleshooting

“Lemon Squeezy would not let this key read the store’s orders.” The key cannot see the store you named. Confirm the store ID belongs to the same account as the key, and create the key with full access. “That store ID does not look right.” Traceten accepts only letters, digits, hyphens and underscores in a store ID, because the value goes into a URL. Copy the number from Settings → Stores. Connected, but revenue is not appearing. Check that the webhook under Settings → Webhooks is still there and pointed at Traceten. If you deleted it, reconnect from the Traceten dashboard. Everything shows as unattributed. Nothing is tying orders back to sessions. Either pass traceten_visitor_id through checkout, or call traceten.identify({ email }) when a visitor signs in. Test-mode orders are missing. Traceten drops test-mode orders in production, because their synthetic amounts would corrupt your revenue totals.

Getting started

Install guide

AI crawlers

AI visibility

Dashboard

Goals and funnels

Integrations

Privacy

What this lets you do

Before you start

Connect Lemon Squeezy

What Traceten does with the key

The signing secret

Keys Traceten will not accept

How attribution works

Refunds and net revenue

Checkout overlay: attribute without writing code

Passing the visitor ID through checkout

What the 90-day import can and cannot match

Verify it worked

Troubleshooting

Next

​What this lets you do

​Before you start

​Connect Lemon Squeezy

​What Traceten does with the key

​The signing secret

​Keys Traceten will not accept

​How attribution works

​Refunds and net revenue

​Checkout overlay: attribute without writing code

​Passing the visitor ID through checkout

​What the 90-day import can and cannot match

​Verify it worked

​Troubleshooting

​Next

What this lets you do

Before you start

Connect Lemon Squeezy

What Traceten does with the key

The signing secret

Keys Traceten will not accept

How attribution works

Refunds and net revenue

Checkout overlay: attribute without writing code

Passing the visitor ID through checkout

What the 90-day import can and cannot match

Verify it worked

Troubleshooting

Next