Endpoint reference

All paths are relative to https://api.base316.com. See Using the API for authentication, errors and pagination.

Access and metering

The two calls on your request path.


`POST /v1/access/check`	May this account do this? Also answers permissions
`POST /v1/events`	Record usage. `idempotencyKey` required


`GET /v1/customers`	List
`POST /v1/customers`	Create
`GET /v1/customers/:id`	One customer
`PATCH /v1/customers/:id`	Update name, email, your id, currency, terms, collection
`GET /v1/customers/:id/billed`	The accounts it pays for, with usage this period
`GET /v1/customers/:id/entitlements`	Every feature as `check` would answer it now, and why


`GET` · `POST /v1/meters`	The raw things you count
`GET` · `PATCH` · `DELETE /v1/meters/:id`
`GET` · `POST /v1/features`	What a customer buys
`GET` · `PATCH` · `DELETE /v1/features/:id`
`GET` · `POST /v1/plans`	Prices and entitlements; each version has `status` and `subscriberCount`
`GET` · `PATCH` · `DELETE /v1/plans/:id`
`POST /v1/plans/:id/versions`	A new immutable version, or a draft with `publish: false`
`PATCH` · `DELETE /v1/plans/:id/versions/:versionId`	Edit or discard a draft. 409 for a published version
`POST /v1/plans/:id/versions/:versionId/publish`	Publish a draft. Idempotent
`GET` · `POST /v1/product-families`	Products
`PATCH` · `DELETE /v1/product-families/:id`
`PUT /v1/plans/:id/family`	File a plan under a product


`GET` · `POST /v1/subscriptions`
`GET /v1/subscriptions/:id`
`GET /v1/subscriptions/:id/upcoming-invoice`	Preview the next invoice. Stores nothing
`GET /v1/subscriptions/:id/plan-change-preview`	`?planVersionId=`. Now vs at period end
`POST /v1/subscriptions/:id/plan-change`	`timing`: `NOW` or `PERIOD_END`
`GET` · `PUT` · `DELETE /v1/subscriptions/:id/phases`	The schedule: a ramp, or its undo
`POST /v1/subscriptions/:id/resume`	Undo a cancellation at period end
`PATCH /v1/subscriptions/:id/quantity`	Change the quantity, prorated
`GET /v1/subscriptions/:id/quantity/preview`	What that change would charge. Stores nothing
`DELETE /v1/subscriptions/:id`	Cancel. `?atPeriodEnd=false` to cancel now
`GET` · `POST` · `DELETE /v1/subscriptions/:id/discounts`	A recurring coupon
`GET` · `POST /v1/subscriptions/:id/price-overrides`	Custom prices for this subscription
`PATCH` · `DELETE /v1/subscriptions/:id/price-overrides/:overrideId`	Edit or remove one
`PATCH /v1/subscriptions/:id/contract`	PO number, invoice memo, billing day
`GET /v1/subscriptions/:id/contract/billing-anchor-preview`	`?billingAnchorDay=`. The stub it creates. Stores nothing


`GET` · `POST /v1/invoices`
`GET /v1/invoices/:id`
`POST /v1/invoices/:id/finalize`	Draft becomes owed
`POST /v1/invoices/:id/pay`	Settle in full
`POST /v1/invoices/:id/void`
`GET` · `POST /v1/invoices/:id/payments`	Record a payment received outside Stripe
`POST /v1/invoices/:id/payments/:paymentId/reverse`	A bounced cheque
`GET /v1/invoices/:id/pdf`	The invoice as a PDF


`GET` · `POST /v1/coupons`
`DELETE /v1/coupons/:id`	Archive
`GET` · `POST /v1/credit-notes`
`POST /v1/credit-notes/:id/void`
`GET /v1/credit-notes/:id/pdf`	As a PDF
`GET` · `POST /v1/tax-rates`
`DELETE /v1/tax-rates/:id`	Archive
`GET /v1/wallets` · `/v1/wallets/:customerId`	Prepaid balance
`POST /v1/wallets/credit` · `/v1/wallets/debit`

Your application's own users and organisations.


`GET` · `POST /v1/users`
`GET` · `PATCH /v1/users/:id`
`POST /v1/users/:id/disable`	Keeps history attributable
`GET` · `POST /v1/organizations`	Your customers' tenants
`PATCH /v1/organizations/:id`	Rename, re-key, default role
`DELETE /v1/organizations/:id`	Delete an empty tenant. `?exceptUserId=`
`GET /v1/organizations/:id/children`	The tenants it manages
`POST /v1/organizations/:id/detach`	Make a managed tenant standalone
`GET` · `PUT /v1/organizations/:id/inherited-roles`	Which parent roles reach the children
`GET` · `PUT /v1/organizations/:id/branding`	A tenant's own look
`GET` · `POST` · `DELETE /v1/organizations/:id/domain`	A tenant's own sign-in domain
`POST /v1/organizations/:id/domain/verify`	Check its DNS
`POST` · `DELETE /v1/organizations/:id/members`
`GET` · `POST /v1/roles` · `GET` · `PATCH` · `DELETE /v1/roles/:id`
`GET` · `POST /v1/permissions` · `GET` · `PATCH` · `DELETE /v1/permissions/:id`
`GET /v1/custom-fields`

End-user sign-in, if you use Base316 for it.


`POST /v1/auth/signup` · `/signin` · `/signout`	Sign-up takes `invitationToken` to join a team instead
`GET /v1/auth/session` · `/sessions`
`POST /v1/auth/sessions/revoke-all`
`POST /v1/auth/password/reset-request` · `/password/reset`
`POST /v1/auth/verify-email`
`POST /v1/auth/mfa/enroll` · `/mfa/confirm` · `/mfa/verify` · `/mfa/disable`
`POST /v1/auth/mfa/required/start` · `/mfa/required/complete`	Enrol a required factor mid-sign-in. Challenge, no session
`GET /v1/auth/password-policy`	Password rules. Publishable key
`POST /v1/auth/code/exchange`	Hosted sign-in callback
`POST /v1/auth/impersonate`	Support access. Audited
`GET /v1/auth/events`	Sign-in history

For a self-serve portal, called with the end user's own session.


------------------------------------------------------------------------------------------	----------------------------------------------------------------
`GET /v1/me/subscription`
`GET /v1/me/subscription/upcoming-invoice`	The user's next bill. 403 `billed_by_parent` for a client tenant
`GET /v1/me/subscription/quantity/preview` · `POST /v1/me/subscription/quantity`	The user's own seat count: preview, then change
`POST /v1/me/subscription/change` · `/cancel`
`GET /v1/me/subscription/plan-change-preview`	What a change would do. `?planVersionId=`
`DELETE /v1/me/subscription/scheduled-change`	Undo a scheduled change
`GET /v1/me/invoices` · `/me/invoices/:id`
`GET /v1/me/invoices/:id/pdf`	One of the user's own invoices, as a PDF
`GET /v1/public/plans` · `/public/branding`	Publishable key. `?organizationId=` for a tenant's brand
`GET /v1/me/organizations`	The person's teams, inherited ones included. Paged with `limit`
`POST /v1/checkout/sessions`


`GET /v1/export/:resource`	`customers`, `subscriptions`, `invoices` as CSV
`GET /v1/import/:resource/template`	An empty file with the right columns
`POST /v1/import/:resource`	`customers`, `subscriptions`, `users`; `skipPastInvoices` for back-dated subscriptions


`GET /v1/payment-accounts`	Stripe Connect status
`POST /v1/payment-accounts/refresh`	Re-read it from Stripe


`GET /v1/whoami`	Which project and environment this key is for