Reference Billing

billing API

Plans, checkout and the Stripe webhook (only with billing enabled).

Base path /api/v1/billing behind the gateway. Authentication, rate limits and the error format are the same for every service: see Scripting MowDeck. Rendered from apps/web/openapi/billing.json (OpenAPI 3.1), which you can also load into any OpenAPI tool.

Operations

billing

POST /api/v1/billing/checkout

Checkout

Start a hosted checkout for plan; redirect the browser to url.

422 when the plan is not sold here, 409 when the account already has a subscription (plan changes and cancellation happen in the customer portal).

Request body (required): application/json CheckoutIn

Status	Meaning	Body
200	Successful Response	application/json RedirectOut
422	Validation Error	application/json HTTPValidationError

GET /api/v1/billing/invoices

Invoices

The newest invoices of the caller's account (links to the provider's pages).

Status	Meaning	Body
200	Successful Response	application/json array of InvoiceOut

POST /api/v1/billing/portal

Portal

Open the provider's customer portal (payment method, invoices, plan change, cancel).

404 before the account's first checkout.

Status	Meaning	Body
200	Successful Response	application/json RedirectOut

GET /api/v1/billing/status

Status

Billing runs here: the provider, the currency and the plans on sale with prices.

Public (a pricing view needs no login). The web app probes it: a network error or 404 (the service is not deployed, billing is disabled) hides every billing element.

Status	Meaning	Body
200	Successful Response	application/json BillingStatusOut

GET /api/v1/billing/subscription

Subscription

The subscription of the caller's account (subscription: null before checkout).

Status	Meaning	Body
200	Successful Response	application/json SubscriptionSummaryOut

POST /api/v1/billing/webhooks/stripe

Stripe Webhook

Stripe events. No token: only the Stripe-Signature over the raw body counts.

400 for an invalid signature, 200 for a handled or repeated event (each event id is processed once), 500 when handling failed (Stripe retries).

Parameter	In	Type	Required	Notes
stripe-signature	header	string or null	no

Status	Meaning	Body
200	Successful Response	application/json WebhookOut
422	Validation Error	application/json HTTPValidationError

Schemas

BillingStatusOut

GET /status: billing runs in this installation and what it sells.

The service only runs when billing is enabled, so a reachable endpoint always says enabled: true; the web app treats a network error or 404 as "billing disabled".

Field	Type	Required	Notes
automatic_tax	boolean	yes	Stripe Tax calculates VAT in Checkout.
currency	string	yes
enabled	boolean	no	default true
plans	array of StatusPlanOut	yes
provider	string	yes

CheckoutIn

Body of POST /checkout.

Field	Type	Required	Notes
plan	string	yes	pattern ^[a-z][a-z0-9_-]{0,63}$

HTTPValidationError

Field	Type	Required	Notes
detail	array of ValidationError	no

InvoiceOut

An invoice reference; the document itself stays at the provider.

Field	Type	Required	Notes
amount_due	integer	yes	Cents.
amount_paid	integer	yes	Cents.
currency	string	yes
hosted_url	string or null	yes
issued_at	string (date-time)	yes
number	string or null	yes
pdf_url	string or null	yes
status	string	yes

PlanStatus

Status of an account's plan.

Type: "active" | "trial" | "grace" | "expired"

PriceOut

A provider price; amounts in the smallest currency unit (cents).

Field	Type	Required	Notes
currency	string or null	yes	ISO 4217, lower case; null when not fetched.
interval	string or null	yes	day, week, month or year.
interval_count	integer or null	yes
price_id	string	yes
unit_amount	integer or null	yes	Amount per interval in cents.

RedirectOut

A provider page to send the browser to.

Field	Type	Required	Notes
url	string	yes

StatusPlanOut

A plan on sale.

Field	Type	Required	Notes
description	string or null	yes
key	string	yes
name	string or null	yes	From Entitlements; null when it is not reachable.
price	PriceOut	yes
trial_days	integer	yes	Trial of a first subscription (from Entitlements).

SubscriptionOut

A subscription as the provider last reported it.

Field	Type	Required	Notes
cancel_at_period_end	boolean	yes
current_period_end	string (date-time) or null	yes
grace_until	string (date-time) or null	yes
plan	string or null	yes
plan_status	PlanStatus or null	yes	What Billing set in Entitlements.
status	SubscriptionStatus	yes
trial_end	string (date-time) or null	yes
updated_at	string (date-time)	yes

SubscriptionStatus

Status of a subscription at the payment provider (Stripe's values).

Type: "incomplete" | "incomplete_expired" | "trialing" | "active" | "past_due" | "canceled" | "unpaid" | "paused"

SubscriptionSummaryOut

GET /subscription: the account's subscription (null before the first checkout).

Field	Type	Required	Notes
has_customer	boolean	yes	The portal can be opened.
provider	string	yes
subscription	SubscriptionOut or null	yes

ValidationError

Field	Type	Required	Notes
ctx	object	no
input	any	no
loc	array of string or integer	yes
msg	string	yes
type	string	yes

WebhookOut

Answer to the provider: received (and what it did, for the logs of the provider).

Field	Type	Required	Notes
duplicate	boolean	yes
event_id	string	yes
outcome	string or null	yes
received	boolean	no	default true

---

Mirrored from docs/reference/api/billing.md at commit 11a94afbcace55924c9675ef400e93c7785b4ac5. Edit the file in the repository, not this wiki page.