Lemon Squeezy data models in Chartsy
Exactly what Chartsy reads from each Lemon Squeezy store, what each object becomes in Chartsy, and what it does with your API key.
How the sync works#
- First import - right after you connect, Chartsy reads each store's products and variants, discounts, customers, subscriptions, subscription invoices and orders, from 1 January two years back, plus every subscription that's still running, however old.
- Live updates - a webhook Chartsy adds to each store sends new orders, subscription payments, refunds and subscription changes as they happen.
- Sync now - re-reads the whole store on request, writes only what changed, and puts the webhook back if it was removed. Lemon Squeezy's lists can't be filtered by date, so there is no hourly sync.
Every record is keyed on Lemon Squeezy's own ids, so the webhook and Sync now can overlap without counting anything twice.
What Chartsy syncs#
| Lemon Squeezy object | Becomes in Chartsy | What is kept |
|---|---|---|
| Product | Product | Name and description |
| Variant | Price | Name, price, currency and billing interval - or one-time |
| Discount | Discount | Code, percentage or fixed amount, and duration |
| Customer | Customer | Email, name, country, city, signup date, and the Chartsy visitor id when your checkout passed one |
| Subscription | Subscription | Status, variant, quantity, its own price (so grandfathered prices are kept), renewal and end dates, trial and pause |
| Subscription invoice | Transaction | Total including tax, tax, Lemon Squeezy’s fee (computed - see below), net amount, currency, billing reason and amount refunded |
| Order | Transaction | The same, for one-time purchases only - a subscription’s first order is already its first invoice |
| Refund | Adjustment | One per payment, as a negative amount, updated as further partial refunds land |
How payments are counted#
- An invoice that starts or renews a subscription counts toward MRR, normalized to a month.
- Upgrade prorations and one-time orders are revenue, not MRR.
- Payments in another currency are converted into your account's currency at the rate on the payment's date.
- Churn is counted when paid access ends, not when the customer clicks cancel: a cancelled subscription counts as active until its end date.
- Full refunds are dated when they were made. Lemon Squeezy only reports a payment's refunded total, so a partial refund from before you connected is dated on the payment.
More on each metric in Metrics.
Lemon Squeezy’s fee#
Lemon Squeezy's API doesn't include the fee it takes from each payment, so Chartsy computes it: your base rate - the standard 5% + $0.50 unless you change it - on the total including tax, plus the published surcharges that apply to that payment (+0.5% on subscriptions, +1.5% for buyers outside the US, +1.5% on PayPal subscription payments). The fee is worked out in US dollars and converted back, as Lemon Squeezy does. Net revenue is the total minus tax and that fee.
The base rate is kept as a history. A new rate recorded from a date applies to payments from that date on; a correction applies to every payment. Payout fees aren't included.
What is left out#
- Usage-based and tiered pricing - counted at the variant's list price.
- License keys and affiliate commissions.
- Checkout custom data other than the Chartsy visitor id.
- Payment details - Chartsy never sees card numbers or bank details.
- With GDPR mode on, customer email, name, country and city, and each payment's country, aren't stored either.
API key and webhooks#
Chartsy connects with one Lemon Squeezy API key, encrypted at rest. It sees every store on your account; only the stores you connect are read. Test-mode keys aren't accepted. Chartsy uses the key to read each store and to manage one webhook per store - the only thing it writes in Lemon Squeezy. The webhook listens for:
| Event | Used for |
|---|---|
order_created | A new order, with the checkout custom data used for attribution |
order_refunded | A refund on a one-time order |
subscription_created | Keeping the subscription current |
subscription_updated | Keeping the subscription current |
subscription_cancelled | Keeping the subscription current |
subscription_resumed | Keeping the subscription current |
subscription_expired | Keeping the subscription current |
subscription_paused | Keeping the subscription current |
subscription_unpaused | Keeping the subscription current |
subscription_payment_success | Subscription payments, failed and recovered |
subscription_payment_failed | Subscription payments, failed and recovered |
subscription_payment_recovered | Subscription payments, failed and recovered |
subscription_payment_refunded | A refund on a subscription payment |
customer_updated | Keeping customer details current |
One key, every store
Lemon Squeezy API keys expire after a year. Every store connected with a key stops syncing when it expires or is deleted. Each store can be connected once, even with a new key, so its numbers are never doubled.
Deleting your data#
Delete a Lemon Squeezy store on the Data Sources page and it is permanently removed, together with everything imported from it. You can also delete the Chartsy webhook in the store's settings and delete the API key in Lemon Squeezy → Settings → API.
