Core concepts
Everything you sell is built from a handful of records. Your code reads the result; the dashboard changes the records.
Apps and accounts
- App
- One product you sell. It has an id (
app_…), a secret key (key_…) and a publishable key (pub_…). Every other record belongs to one app. A dashboard workspace can hold several apps. - Account
- One customer of your app: a user, a team or an organization, keyed by an id you choose. The API calls accounts
namespaces, so routes look like/apps/:appId/namespaces/:id. An account is always on exactly one plan.
What you sell
- Entitlement
- One thing an account can use. A
booleanentitlement is on or off (“exports”). Ausageentitlement is counted against a limit (“1,000 contacts”), or unlimited. Usage entitlements can block usage past the limit and answer with an upgrade offer. - Plan
- A named bundle of entitlements, each with its own limit, plus add-ons, pricing and free-form metadata. Plans carry monthly and yearly prices or a one-time price, and one can be marked free.
- Add-on
- A named extra, such as priority support or a welcome call. Plans, offers and incentives can include add-ons, and an account can own add-ons directly.
- Incentive
- A per-account override: higher limits, extra entitlements or add-ons for one customer, with an optional expiry. Use it for trials, partner deals and goodwill credits. An account has at most one.
- Offer
- A way to buy. It lists which plans are for sale, at what price per interval, with an optional intro discount, extra entitlements for buyers, order bumps, an expiry and a redemption cap. Each offer has its own link, so you can run one per campaign or affiliate.
How access is resolved
When you ask for an account's plan, the API builds it in three layers. Each layer overrides the one before it for any entitlement they share.
| Layer | Comes from | Applies while |
|---|---|---|
| 1. Plan | The account's plan | Always |
| 2. Offer extras | The offer the account bought through | The subscription is active, and the extras haven't ended with the intro price or after their set duration |
| 3. Incentive | The incentive on the account | Until its expiry, if it has one |
Add-ons from every layer are merged with the account's own. Each entitlement comes back with the account's current usage and a ready answer:
{ "id": "contacts", "feature": "contacts", "name": "Contacts", "type": "usage", "usage": 940, "max": 1000, "left": 60, "can": true }can is the field to gate on. max: null means unlimited. Two routes return this shape: /plan hides plan metadata keys you marked private, and full-plan includes them.
Usage
Usage is a counter per account and entitlement. Your code moves it with add, remove or amount, and each change is also kept as an event for analytics. By default usage can go past the limit and can turns false. When an entitlement blocks overage, the limit is checked in the same atomic update, so two requests at the limit can't both get through. Counters don't reset by themselves at the end of a billing period.
Subscriptions and checkouts
A checkout is one attempt to buy through an offer. The API prices it on the server from the offer's records, whatever the browser sends, and hands it to PayPal. When PayPal confirms the payment, the account moves to the plan it bought and the purchase is recorded on the account as its subscription: the offer, the price, discounted cycles left and the renewal date.
Plan changes, cancellations and pauses all work on that subscription. Cancelling moves the account to your free plan; pausing suspends billing in PayPal and moves the account to the free plan until the pause ends. PayPal covers the details.
Cancel flows
A cancel flow is the set of steps a customer sees when they press cancel: questions about why, a save offer, and a confirmation. The save offer can be a discount, a pause, a downgrade or an incentive. It can be fixed, or picked per customer by an AI agent inside limits you set. See Cancel flows in the dashboard docs.
Events
Changes produce events, such as account.plan_changed, usage.limit_reached or checkout.completed. The API keeps 30 days of them and delivers each to the webhook endpoints that subscribe to its type. See Webhooks.