Lemon Squeezy Webhook

Lemon Squeezy Webhook

Each stored delivery is one Lemon Squeezy webhook POST — a JSON:API object with meta and data. The event name lives in meta.event_name; the resource body is under data with type, id, and attributes. Tools read what already landed; there is no pull API and no way to refund, cancel subscriptions, or replay webhooks from here.

First moves

1. Latest report — default for “what order or subscription event happened last”.
2. Read export.json.meta.event_name — classify the delivery before quoting money or access state.
3. Inspect export.json.data.type and data.attributes — order, subscription, subscription invoice, license key, customer, or affiliate shapes differ.
4. Recent reports — scan history when deduping retries, tracing a buyer, or separating test-mode traffic.
5. One report by id — after listing, when the user points at a specific capture.

Payload envelope

Start every read from export.json:

• meta.event_name — mirrors the upstream event (also sent as an HTTP header on delivery). Examples: order_created, order_refunded, subscription_created, subscription_updated, subscription_cancelled, subscription_resumed, subscription_expired, subscription_paused, subscription_unpaused, subscription_payment_success, subscription_payment_failed, subscription_payment_recovered, subscription_payment_refunded, license_key_created, license_key_updated, customer_updated, affiliate_activated.
• meta.custom_data — checkout custom fields you attached upstream (user ids, plan codes, campaign tags). Present on order, subscription, and license-key events when configured; keys and values are entirely store-defined.
• data.type — JSON:API resource kind: orders, subscriptions, subscription-invoices, license-keys, customers, affiliates.
• data.id — stable resource id string for deduping across retries.
• data.attributes — event-specific fields (money, buyer, product, subscription state).

Order events (meta.event_name order_created or order_refunded)

When data.type is orders, read from data.attributes:

• Identity — identifier (UUID-style order id), order_number, store_id, customer_id.
• Buyer — user_name, user_email.
• Money — subtotal, discount_total, tax, total in order currency minor units (cents); parallel *_usd and *_formatted fields when present. Divide cent integers by 100 for dollar amounts unless the user asked for cents.
• Status — status, status_formatted, refunded, refunded_at.
• Line item snapshot — first_order_item with product_id, variant_id, product_name, variant_name, price, and test_mode on the line item.
• Timing — created_at, updated_at on the order; compare with source.captured_at for when the POST landed here.

Subscription events (subscription_* on data.type subscriptions)

Common subscription fields in data.attributes:

• Product — product_id, variant_id, product_name, variant_name.
• Buyer — user_name, user_email, customer_id.
• State — status (active, on_trial, paused, past_due, unpaid, cancelled, expired, …), status_formatted, cancelled, pause.
• Billing timing — renews_at, ends_at (scheduled expiry while cancelled or after dunning), trial_ends_at, billing_anchor.
• Links to buyer self-service — urls.customer_portal, urls.update_payment_method (signed URLs; not the same as webhook signing).
• Test purchases — test_mode boolean on attributes (and often on related order line items).
• First item — first_subscription_item with price_id, quantity when present.

Lifecycle notes when interpreting history:

• A new subscription typically produces separate stored deliveries for order_created, subscription_created, and subscription_payment_success (and license_key_created when licenses are enabled) — do not treat one capture as the full story.
• subscription_updated fires on many later changes (renewals, payment-method updates, cancellations). Granular events like subscription_resumed or subscription_expired may also arrive; dedupe on data.id plus meta.event_name when counting unique business moments.
• subscription_payment_recovered is always paired with subscription_payment_success after a failed renewal is retried.

Subscription invoice events (subscription_payment_*)

When data.type is subscription-invoices, the payload is an invoice object (renewal charge, failed charge, refund) rather than the subscription record itself. Read invoice totals, status, and linked subscription ids from data.attributes and cross-reference subscription captures by id when the user asks about recurring billing history.

License key events (license_key_created, license_key_updated)

When data.type is license-keys, read key status, activation limits, and linked order or subscription ids from data.attributes. A new licensed purchase also sends separate order_created (and often subscription_created) deliveries.

Response shape

• export.json — parsed webhook body; start with meta.event_name, then data.type and data.attributes.
• export.text — raw body when JSON is large or parsing failed.
• source.captured_at — when the POST landed here, not necessarily data.attributes.created_at.

Operational order

1. Start with the latest report — do not guess a report id.
2. State meta.event_name and data.type before summarizing revenue or access.
3. Check test_mode before quoting production totals.
4. Read meta.custom_data when the user tracks internal ids from checkout.
5. If captured_at is older than expected, say so — events arrive when upstream fires them (renewals, refunds, lifecycle changes), not on demand.
6. List recent reports only for history, duplicate suspicion, or tracing one buyer across events.
7. Read ## This connection in the skill supplement for store-specific product or custom_data field notes.

Gotchas

• Read-only — cannot place orders, issue refunds, cancel subscriptions, or acknowledge deliveries upstream.
• JSON:API shape — fields live under data.attributes, not at the top level; do not assume a flat Gumroad-style envelope.
• Duplicate bursts — one checkout can produce several stored deliveries within seconds; dedupe on data.id and meta.event_name, not capture order alone.
• Retries — failed upstream delivery retries up to three times with exponential backoff; the same event may appear more than once with different source.captured_at.
• Money is in cents — total, subtotal, and line-item price are integer minor units unless *_formatted strings are present.
• test_mode — filter test checkouts and simulated subscription events before revenue or activation decisions.
• Signature domain note — upstream signs the exact raw POST bytes with HMAC-SHA256 in the X-Signature header. Re-serializing or pretty-printing JSON before verification changes the bytes and breaks the hash; stored export.json is already parsed for reading, not for re-signing. Receipt and portal URLs inside the payload carry their own query signature parameters — those are unrelated to webhook X-Signature.
• Variable presence — meta.custom_data, first_order_item, license fields, and subscription invoice payloads appear only for relevant products and event types; absence is normal.