Managing Billing and Subscriptions
ButtrBase now uses a quote-to-checkout-to-webhook billing flow.
Redirect success pages are not authoritative. Subscription and invoice state is finalized by provider webhooks.
Step 1: Preview Pricing
Endpoint: POST /api/pricing/preview
~~~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).
Step 2: Create a Quote
Endpoint: POST /api/pricing/quote
~~~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).
Step 3: Launch Checkout
Endpoint: POST /api/pricing/checkout-session
~~~json { "quote_id": "signed-quote-token" } ~~~
Output: ~~~json { "data": { "id": "provider-session-id", "url": "https://provider.example/checkout/...", "provider": "stripe" } } ~~~
Step 4: Wait For Webhook Confirmation
Provider webhooks finalize local billing state:
POST /api/billing/webhooks/stripePOST /api/billing/webhooks/paypal
Step 5: Read Billing State
Endpoint: GET /api/billing/history
~~~json { "data": [ { "id": 124, "provider_invoice_id": "in_123", "amount": 2500, "status": "paid" } ] } ~~~