Billing & Subscriptions API

The canonical checkout flow uses the pricing decision endpoints, then webhook confirmation.

Checkout Flow

POST /api/pricing/preview

Previews the localized customer-facing price.

Input: ~~~json { "price_id": 1, "region": "us", "ip_address": "8.8.8.8", "currency": "usd", "seats": 5 } ~~~

(Note: Providing ip_address allows the platform to automatically determine the optimal regional price if region or country is missing).

POST /api/pricing/quote

Creates a signed short-lived quote.

POST /api/pricing/checkout-session

Creates a provider checkout session from a previously created quote_id.

Input: ~~~json { "quote_id": "signed-quote-token" } ~~~

GET /api/billing/history

Retrieves the billing history.

Output: ~~~json { "data": [{ "id": 124, "amount": 2000, "status": "paid" }] } ~~~

GET /api/billing/cards

Lists stored payment methods for the authenticated user.

POST /api/billing/cards

Adds a stored payment method for the authenticated user.

PUT /api/billing/cards/default

Sets the default stored payment method.

POST /api/billing/webhooks/:provider

Authoritative provider webhook ingestion endpoint.

Supported providers:

• stripe
• paypal

Response: ~~~json { "received": true } ~~~