Billing

Plans, checkout, subscriptions, invoices and entitlements. Your code checks what a person is allowed to do, not which price they pay.

Plans and entitlements

A plan has a price and a set of entitlements: named features and limits.

JSON

{
  "id": "plan_pro",
  "name": "Pro",
  "interval": "month",
  "amount": 1200,
  "currency": "usd",
  "entitlements": {
    "export.pdf": true,
    "seats": 5,
    "ai.summaries.per_month": 500
  }
}

Change a plan's entitlements in the dashboard and every subscriber gets the change on their next request, without a deploy. Plans can belong to one app or be shared by all of them.

Checking entitlements

Terminal

curl https://api.dianthan.com/v1/me/entitlements \
  -H "Authorization: Bearer $TOKEN"

JSON

{ "entitlements": { "export.pdf": true, "seats": 5, "ai.summaries.per_month": 500 } }

Check one with GET /v1/me/entitlements/export.pdf. Organizations have their own at GET /v1/organizations/:id/entitlements. A person who belongs to a paying organization gets its entitlements as well as their own.

Checkout

Terminal

curl -X POST https://api.dianthan.com/v1/billing/checkout \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "plan_id": "plan_pro",
    "success_url": "https://fieldnotes.app/welcome",
    "cancel_url": "https://fieldnotes.app/pricing"
  }'

The response contains a hosted checkout url; redirect to it. Pass "organization_id" to bill a team, or "mode": "payment" for a one-off charge. Success and cancel URLs must be on the app's registered domains.

When the payment completes, Dianthan records the subscription and updates entitlements, usually before the person's browser reaches success_url.

The customer portal

POST /v1/billing/portal returns a link to the hosted self-service portal, where customers update cards, download invoices and cancel. You can also cancel and resume from your own interface with POST /v1/billing/subscriptions/:id/cancel and /resume.

The local ledger

Customers, subscriptions and invoices are recorded from verified payment events, and each event is applied exactly once, even if it is delivered twice. Reads such as GET /v1/billing/subscriptions and GET /v1/billing/invoices are served from this ledger, so they are fast and consistent.

Grants and overrides

From the dashboard, or with POST /v1/billing/subscriptions using an admin credential, you can give someone a plan without charging them. Entitlement overrides switch on one feature for one account without changing their plan, which is useful for a beta or a support case.

Settlement

Payments settle to your merchant account. Dianthan takes no share of them; card processing fees apply as usual.

In preview: connecting your merchant account from the dashboard. Until then, accounts are connected by our team on request.