# Plinth

## Docs

- [Advance the clock](https://docs.useplinth.xyz/api-reference/advance-clock.md): Fast-forwards simulated time by the specified number of seconds. The shared sandbox clock is rate-limited to 1 advance per minute. After advancing, call `POST /admin/tick` to trigger billing.
- [Authentication](https://docs.useplinth.xyz/api-reference/authentication.md): All API requests require a Bearer token in the Authorization header.
- [Cancel scheduled change](https://docs.useplinth.xyz/api-reference/cancel-scheduled-change.md): Cancels a pending at-period-end plan change. The subscription stays on the current plan.
- [Cancel a subscription](https://docs.useplinth.xyz/api-reference/cancel-subscription.md): Cancel now or at period end, following the tenant cancel policy.
- [Checkout-funded plan change](https://docs.useplinth.xyz/api-reference/change-checkout.md): Upgrade a subscription that has no card on file by collecting the proration via checkout.
- [Change plan](https://docs.useplinth.xyz/api-reference/change-plan.md): Commits a plan change. For upgrades (by default): charges the prorated difference immediately. For downgrades (by default): schedules the change at the next period end — no charge now. This behaviour is controlled by your TenantPolicy preset.
- [Create a checkout link](https://docs.useplinth.xyz/api-reference/checkout-link.md): Generate a Nomba-hosted checkout to pay-to-unlock or recover a subscription.
- [Create a customer](https://docs.useplinth.xyz/api-reference/create-customer.md): Creates a new customer. Set `external_ref` to your own system's user ID so you can look up customers by your ID later.
- [Create a plan](https://docs.useplinth.xyz/api-reference/create-plan.md): Creates a plan within a plan group. Amount is in kobo. Set `trial_period_days` to give new subscribers a free trial before the first charge. Set `lookup_key` to a stable handle (e.g. `pro_monthly`) so your app can reference the plan by role instead of by UUID.
- [Create a plan group](https://docs.useplinth.xyz/api-reference/create-plan-group.md): A plan group is a named collection of plans (e.g., "Core" containing Starter, Pro, Max). Create the group first, then add plans to it.
- [Create a sandbox](https://docs.useplinth.xyz/api-reference/create-sandbox.md): Provisions an isolated sandbox tenant pre-seeded with three plans (Starter, Pro, Max) and one test customer. Returns a private API key. No authentication required. The sandbox expires after 24 hours.
- [Create a subscription](https://docs.useplinth.xyz/api-reference/create-subscription.md): Subscribes a customer to a plan. If the plan has a trial period, the subscription starts in `trialing` state and the first charge fires at `trial_end_at`. Use `preferred_rail: transfer` for customers who pay by bank transfer.
- [Delete or archive a plan](https://docs.useplinth.xyz/api-reference/delete-plan.md): **Archive-by-default.** If the plan has any subscriptions it is *archived* (`active=false`): existing subscribers keep billing, history is preserved, and it stops accepting new sign-ups. Only a plan that was never subscribed is permanently hard-deleted. Historical invoices are never affected either…
- [Get clock state](https://docs.useplinth.xyz/api-reference/get-clock.md): Returns the current simulated time (test mode only).
- [Get customer entitlements](https://docs.useplinth.xyz/api-reference/get-customer-entitlements.md): Returns whether the customer has access to paid features and at what tier. Use this before serving any feature — don't parse subscription state yourself. Returns `has_access: false` if the customer has no subscription.
- [Get subscription status](https://docs.useplinth.xyz/api-reference/get-subscription-status.md): Returns the current access status for a subscription.
- [List plans](https://docs.useplinth.xyz/api-reference/list-plans.md): Returns the tenant's plans. **Active-only by default** — pass `include_archived=true` to include archived plans too.
- [List suspense items](https://docs.useplinth.xyz/api-reference/list-suspense.md): Returns unresolved inbound transfers that couldn't be matched to a customer or open invoice. Resolve them manually or wait for the customer to contact you.
- [Preview a plan change](https://docs.useplinth.xyz/api-reference/preview-plan-change.md): Calculates exactly what a plan change would cost without committing it. Always call this before `change` so the customer sees the exact amount before confirming. Returns proration amounts to the kobo.
- [Provision a virtual account](https://docs.useplinth.xyz/api-reference/provision-virtual-account.md): Creates a dedicated bank account number (virtual account) for the customer. Transfers sent to this account are automatically matched to open invoices. One virtual account per customer.
- [Reactivate a subscription](https://docs.useplinth.xyz/api-reference/reactivate-subscription.md): Undo a pending end-of-period cancel so the subscription keeps renewing.
- [Reset the clock](https://docs.useplinth.xyz/api-reference/reset-clock.md): Switches the clock back to real-time mode.
- [Resolve a suspense item](https://docs.useplinth.xyz/api-reference/resolve-suspense.md): Marks a suspense transfer as manually resolved with an audit note.
- [Run billing tick](https://docs.useplinth.xyz/api-reference/run-tick.md): Processes all subscriptions due for billing, trials ending, dunning retries, grace period checks, and expired sandbox cleanup. Must include `tenant_id` as a query parameter.
- [Update a plan](https://docs.useplinth.xyz/api-reference/update-plan.md): Updates a plan. Marketing fields (name, `lookup_key`, trial days, `active`) can always be changed. **Price and billing interval are immutable once the plan has subscribers** — attempting to change them returns 400 (`plan_immutable`). To change a price, create a new plan and migrate subscribers with…
- [Webhook endpoints](https://docs.useplinth.xyz/api-reference/webhooks.md): Manage the endpoints Plinth delivers signed events to.
- [Changelog](https://docs.useplinth.xyz/changelog.md): What changed and when.
- [Customers](https://docs.useplinth.xyz/core-concepts/customers.md): A customer is who you are billing. One customer can have multiple subscriptions.
- [Invoices](https://docs.useplinth.xyz/core-concepts/invoices.md): An invoice is created on each billing cycle. It records what a customer owes for a period.
- [Plans & pricing](https://docs.useplinth.xyz/core-concepts/plans.md): A plan sets the price and billing interval. Customers subscribe to plans.
- [Subscriptions](https://docs.useplinth.xyz/core-concepts/subscriptions.md): A subscription is a recurring billing relationship between a customer and a plan.
- [Tenants & API keys](https://docs.useplinth.xyz/core-concepts/tenants.md): A tenant is your company account. Everything — customers, plans, invoices — lives under it.
- [Webhooks & events](https://docs.useplinth.xyz/core-concepts/webhooks.md): We send a signed webhook every time something important happens — subscription renewed, payment failed, plan changed.
- [Arrears / postpaid billing](https://docs.useplinth.xyz/guides/arrears-billing.md): Invoice at the end of the period instead of the beginning. Useful for usage-based or enterprise contracts.
- [Card billing (SaaS-Standard setup)](https://docs.useplinth.xyz/guides/card-billing.md): The standard SaaS flow: tokenise a card once, charge automatically on renewal.
- [Failed payments: dunning → grace → recovery](https://docs.useplinth.xyz/guides/dunning.md): What happens when a card declines, and how we recover the revenue.
- [Upgrade & downgrade with proration](https://docs.useplinth.xyz/guides/plan-changes.md): Move a customer between plans mid-cycle. We calculate what they owe (or are owed) to the second.
- [Receiving webhooks](https://docs.useplinth.xyz/guides/receiving-webhooks.md): React to Plinth events in your app — register an endpoint, verify the signature, handle the event.
- [Using the test clock](https://docs.useplinth.xyz/guides/test-clock.md): Fast-forward time in your sandbox to test renewals, dunning, and grace periods without waiting.
- [Transfer billing (virtual account setup)](https://docs.useplinth.xyz/guides/transfer-billing.md): For customers who prefer to pay by bank transfer. Every customer gets a dedicated account number.
- [How the money flows](https://docs.useplinth.xyz/how-money-flows.md): From customer to plan to invoice to ledger — the full picture in plain English.
- [What is Plinth?](https://docs.useplinth.xyz/introduction.md): Recurring billing for Nigerian SaaS — card charging, bank transfers, and dunning in one API.
- [Lenient](https://docs.useplinth.xyz/presets/lenient.md): For B2B customers where losing one account hurts more than waiting on payment.
- [Billing presets](https://docs.useplinth.xyz/presets/overview.md): Named policy bundles. Pick one and your billing behaviour is configured. Change individual knobs later if you want.
- [Postpaid / Arrears](https://docs.useplinth.xyz/presets/postpaid.md): Bill at the end of the period. For usage-based and enterprise contract billing.
- [SaaS-Standard](https://docs.useplinth.xyz/presets/saas-standard.md): The right default for most subscription SaaS businesses.
- [Strict](https://docs.useplinth.xyz/presets/strict.md): For services where access and payment are tightly coupled. Short grace, no exceptions.
- [Transfer-First](https://docs.useplinth.xyz/presets/transfer-first.md): Built for customer bases that primarily pay by bank transfer.
- [5-minute quickstart](https://docs.useplinth.xyz/quickstart.md): Create a customer, subscribe them to a plan, and check their access. Three API calls.
- [Sandbox](https://docs.useplinth.xyz/sandbox.md): Test against a live API without a Nomba account. Two options: shared (instant) or your own isolated environment.
- [Node.js SDK](https://docs.useplinth.xyz/sdk.md): A thin, typed wrapper around the REST API. Install it and you have types for everything.
- [Webhook events catalog](https://docs.useplinth.xyz/webhook-events.md): Every event type we emit, what triggers it, and what the payload looks like.

## OpenAPI Specs

- [openapi](https://docs.useplinth.xyz/openapi.yaml)