Polar data models in Chartsy
Exactly what Chartsy reads from one Polar organization, what each object becomes in Chartsy, and the token scopes it needs.
How the sync works#
- First import - right after you connect, Chartsy reads your products and prices, discounts, customers, subscriptions, orders and refunds, from 1 January two years back, plus every subscription that's still active, however old.
- Live updates - a webhook endpoint Chartsy adds in Polar sends new orders, refunds and subscription changes as they happen.
- Hourly catch-up - picks up anything a webhook missed, and switches the endpoint back on if Polar disabled it after failed deliveries.
Every record is keyed on Polar's own ids, so the webhook and the hourly sync can overlap without counting anything twice.
What Chartsy syncs#
| Polar object | Becomes in Chartsy | What is kept |
|---|---|---|
| Product | Product | Name, description, billing interval, visibility, whether it is archived |
| Price | Price | Amount, currency and interval. Fixed, per-seat, metered, pay-what-you-want and one-time prices are all kept; per-seat prices use the first tier’s price per seat |
| Discount | Discount | Code, percentage or fixed amount, duration, redemptions and expiry |
| Customer | Customer | Email, name, country, city, signup date, your external_id, and the Chartsy visitor id when your checkout passed one |
| Subscription | Subscription | Status, seats, amount per period, interval, current period, cancel at period end, trial and pause dates, discounts, cancellation reason |
| Order | Transaction | Total including tax, tax, Polar’s fee, net amount, currency, billing reason, invoice number, country, amount refunded |
| Refund | Adjustment | Negative amount including tax, tied to its order; refunds from disputes are recorded as chargebacks |
How orders are counted#
- An order that creates or renews a subscription bills a full period, so it counts toward MRR.
- Upgrade prorations, metered usage and one-time purchases are revenue, not MRR.
- Orders still awaiting payment aren't revenue until they're paid.
- Orders in another currency are converted into your account's currency at the rate on the order's date.
- Churn is counted when paid access ends, not when the customer clicks cancel.
More on each metric in Metrics.
What is left out#
- Draft and void orders, and refunds that failed or were cancelled.
- Custom customer metadata - only
external_idand the Chartsy visitor id are kept, so other fields don't become breakdowns. - Payment details - Chartsy never sees card numbers or bank details.
- With GDPR mode on, customer email, name, country and city aren't stored either.
Token scopes#
Chartsy connects with one Organization Access Token, encrypted at rest. It checks each scope when you connect and names any that are missing.
| Scope | Used for |
|---|---|
organizations:read | Finding your organization and its name |
products:read | Reading your products |
subscriptions:read | Reading your subscriptions |
orders:read | Reading your orders |
refunds:read | Reading your refunds |
customers:read | Reading your customers |
discounts:read | Reading your discounts |
webhooks:write | Adding the webhook endpoint - the only thing Chartsy writes in Polar. Without it, data syncs hourly instead. |
Already connected this organization?
Each Polar organization can be connected once, even with a new token, so its numbers are never doubled.
Deleting your data#
Delete the Polar source on the Data Sources page and it is permanently removed, together with everything imported from it. You can also revoke the token and delete the webhook endpoint in your Polar organization's settings.
