> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lemon Squeezy Integration

> Sync Lemon Squeezy customers, subscriptions, and completed revenue into Sequenzy

Connect one Lemon Squeezy store to a Sequenzy workspace to sync billing state,
MRR, LTV, and subscription lifecycle events. Your existing Lemon Squeezy
checkout remains the source of purchases; Sequenzy does not create a separate
checkout or product catalog.

## Connect your store

You need a Lemon Squeezy API key and the numeric store ID.

1. Open **Settings → Integrations → Lemon Squeezy** in Sequenzy.
2. Enter the API key and store ID.
3. Leave **Manual webhook setup** off for the recommended managed setup.
4. Select **Connect Lemon Squeezy**.

Sequenzy validates the key, confirms access to the requested store, detects
live or test mode, creates a signed webhook, and then queues the initial
revenue sync. API keys expire or can be rotated; reconnect the integration
after replacing a key.

<Note>
  Lemon Squeezy keeps live and test data separate. A test-mode key creates a
  test-mode webhook and syncs only test data.
</Note>

### Manual webhook fallback

If the API key cannot manage webhooks, enable **Manual webhook setup** and
provide your own 16-40 character signing secret. Create the webhook in Lemon
Squeezy with the URL returned by Sequenzy:

```text theme={null}
https://api.sequenzy.com/api/webhooks/lemon_squeezy/{companyId}
```

Subscribe it to exactly these events:

```text theme={null}
order_created
order_refunded
customer_updated
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
```

Reconnecting a managed integration rotates its signing secret. Disconnecting
deletes only webhooks managed by Sequenzy; manual webhooks remain under your
control.

## Synced data

The initial sync walks every page of customers, subscriptions, orders, and
subscription invoices. Only Price and Variant details referenced by a
subscription are fetched; Sequenzy does not mirror the complete Lemon Squeezy
catalog.

Subscribers are matched by email and receive `mrr`, `ltv`, billing tags, and:

| Attribute                    | Description                                |
| ---------------------------- | ------------------------------------------ |
| `lemonSqueezyCustomerId`     | Lemon Squeezy customer ID                  |
| `lemonSqueezySubscriptionId` | Most recently changed live subscription ID |
| `lemonSqueezyProductId`      | Current product ID                         |
| `lemonSqueezyVariantId`      | Current variant ID                         |
| `lemonSqueezyPriceId`        | Current Price resource ID                  |
| `lemonSqueezyPlanName`       | Current product or variant name            |
| `lemonSqueezyInterval`       | Day, week, month, or year                  |
| `lemonSqueezyStatus`         | Latest subscription status                 |
| `lemonSqueezyRenewsAt`       | Next renewal timestamp                     |
| `lemonSqueezyEndsAt`         | End of a cancellation grace period         |

Multiple subscriptions remain independent when MRR is calculated. The scalar
plan fields describe the most recently changed live subscription.

## Revenue calculation

MRR normalizes standard recurring prices across daily, weekly, monthly, and
yearly intervals. Usage-based and tiered subscriptions cannot be projected
from a fixed unit price, so Sequenzy uses the latest paid subscription invoice
as a trailing MRR estimate.

LTV includes successful orders and subscription invoices, net of refunds.
Lemon Squeezy emits companion events for the first subscription payment and for
payment recovery; Sequenzy deduplicates those events. Partial refunds reduce
LTV only by the increase in the provider's cumulative refunded amount.

## Lifecycle behavior

* `cancelled` retains access and MRR through `ends_at`; expiration emits
  `saas.churn` and removes MRR.
* `past_due` remains live while Lemon Squeezy retries payment.
* `unpaid` and `paused` remove MRR without emitting terminal churn.
* Resume or unpause restores the subscription state without inventing a
  purchase.
* A recurring amount change on `subscription_updated` emits `saas.upgrade` or
  `saas.downgrade` based on the prior normalized amount.
* Successful charges emit `saas.purchase`, plus monthly or yearly purchase
  classification when applicable. Failures and refunds emit
  `saas.payment_failed` and `saas.refund`.
* Customer updates refresh profile data without triggering an automation.

Lemon Squeezy does not expose an abandoned-checkout webhook event, so this
integration cannot emit `saas.checkout_expired`.

## Delivery, retries, and limits

Webhook signatures are verified from the raw request body with Lemon
Squeezy's `X-Signature` HMAC-SHA256 scheme. Valid deliveries are queued before
subscriber updates run. Identical payloads, provider retries, and companion
events are idempotent.

The Lemon Squeezy API is limited to 300 requests per minute. Sequenzy requests
100 records per page and applies bounded backoff to rate limits and transient
failures. Lemon Squeezy retries webhook deliveries when Sequenzy returns a
non-success response.

See Lemon Squeezy's [API documentation](https://docs.lemonsqueezy.com/api),
[webhook event list](https://docs.lemonsqueezy.com/help/webhooks/event-types),
and [testing guide](https://docs.lemonsqueezy.com/guides/developer-guide/testing-going-live).

## Disconnect and retry cleanup

Use Settings → Integrations, `sequenzy integrations disconnect <id>`, MCP
`disconnect_integration`, or [Disconnect Integration](/api-reference/integrations/disconnect).
Disconnection stops ingestion and fences in-flight syncs before removing the
managed webhook. Your subscribers and history remain. Manual webhooks are not
deleted. If `cleanupWarning` is non-null, local disconnection has succeeded;
repeat disconnect to retry provider cleanup. Reconnect with valid credentials
to resume ingestion.