Documentation

Lemon Squeezy guide

Subscribe to order_created, order_refunded, subscription_created, subscription_payment_success, and subscription_payment_refunded. Verify X-Signature as a hex HMAC-SHA256 over the exact body using the literal signing secret. The provider does not sign a timestamp; durable transaction-scoped persistence prevents replay. Signature scheme, event catalog.

Orders use data.id, attributes.total and currency, with product information in first_order_item.product_id. Subscription invoices use their own resource ID and billing_reason; renewal is recurring revenue. initial invoices are aliases of the original order and never add financial revenue. subscription_created supplies the subscription's order_id and product_id mapping, including for filtered renewals arriving early. Order object, invoice object, subscription mapping.

Refund refunded_amount values are cumulative minor-unit balances. Initial invoice refunds map back to the order. Each transaction snapshot is retained; differences are booked on provider updated_at dates, so repeated or out-of-order deliveries do not over-subtract or misdate partial refunds. Initial invoice refund example.

Hosted merchant links accept checkout[custom][ml_visitor_id] and checkout[custom][ml_session_id]. Custom metadata returns under meta.custom_data. Server-created checkouts use checkout_data.custom. Only explicitly allowed merchant origin/path combinations are tagged. Official custom-data guide.

Keep subscription_created enabled. Without it, initial invoice refunds wait for mapping and filtered renewal invoices with no product evidence remain pending; the adapter never guesses an order/product from email or timing. Multi-product orders use only the product information delivered by the webhook; there is no API expansion in this stream.