Billing API

Plan, checkout, portal, and invoice endpoints backed by Stripe.

GET /api/billing/plan

Returns the active plan for the current user.

{
  "plan": {
    "id": "pro",
    "name": "Xcity Pro",
    "renews_at": "2026-06-01T00:00:00Z",
    "entitlements": ["full-catalog", "priority-routing"]
  }
}

Used by sub-products to render gating and entitlements without each app holding Stripe credentials.

POST /api/billing/checkout

POST /api/billing/checkout
Content-Type: application/json

{ "price_id": "price_..." }

Returns { url: "..." } — a one-time Stripe Checkout session URL. Redirect the user there. On success they return to /dashboard/billing?success=1.

GET /api/billing/portal

Returns { url: "..." } — a one-time Stripe Customer Portal URL where the user manages payment methods, switches plans, and downloads invoices.

GET /api/billing/invoices

Returns the user’s invoice history.

{
  "invoices": [
    { "id": "in_...", "amount": 2900, "currency": "usd", "status": "paid", "created": 1747000000, "pdf_url": "..." }
  ]
}

POST /api/billing/webhook

Stripe → xcity-home only. Not for client use. Receives:

  • checkout.session.completed
  • customer.subscription.created
  • customer.subscription.updated
  • customer.subscription.deleted
  • invoice.payment_failed

Updates app_metadata.plan on the GoTrue user. Signature verification is mandatory — see Operations: Stripe webhooks.

Last updated: