Billing

Stripe-backed billing for the caller's current organization. Every operation resolves the Stripe customer from the authenticated user's current organization (organization.stripeCustomerId) and requires the manageBilling ability on that organization (enforced by StripePolicy). The organization is taken from the access token's current-organization context, not from a request parameter, so no organization id is passed in the body or path. The platform is a thin proxy in front of Stripe: success payloads are the native Stripe resource objects (Customer, Subscription, ...) wrapped in the standard { "success": true, "data": ... } envelope.

📄️ Get the current organization's Stripe customer

Retrieves the Stripe `Customer` for the authenticated user's current organization. The customer id is read from `organization.stripeCustomerId`; a `404` is returned when the organization has no customer yet, or when the stored customer has been deleted in Stripe (in which case the stale id is cleared server-side). Requires the `manageBilling` ability.

📄️ Create (or reuse) the organization's Stripe customer

Creates a Stripe `Customer` for the authenticated user's current organization and persists its id to `organization.stripeCustomerId`. Idempotent per organization: if the organization already carries a live customer id a `409` is returned, and if a Stripe customer already exists for the given `email` whose `metadata.organization_id` matches this organization, that existing customer is re-synced and returned with `200` rather than creating a duplicate. The created customer is tagged with `metadata.organization_id` and configured for automatic tax (the request IP is used for location validation). Requires the `manageBilling` ability.

📄️ List the organization's Stripe subscriptions

Lists the Stripe `Subscription` objects for the current organization's customer (`stripe.subscriptions.list({ customer })`). Returns the native Stripe list object (`{ object: 'list', data: [...] }`). Requires the `manageBilling` ability.

📄️ Create a Stripe subscription for the organization's customer

Creates a Stripe `Subscription` for the supplied `customerId` against one or more prices, tagging it with `metadata.organization_id`. Requires the `manageBilling` ability.

📄️ List an organization's issued invoices

Lists the given organization's invoices that have moved past the draft stage (`issued`, `paid`, or `void`), each with its line items preloaded, ordered by billing period descending. Draft invoices are generated internally by platform admins ahead of issuance and are never exposed to the client.

📄️ Get one of an organization's issued invoices

Gets a single invoice belonging to the given organization, its line items preloaded. A draft invoice is treated as not found so its existence never leaks to the client ahead of issuance; the same applies to an invoice that exists but belongs to a different organization.

📄️ Get an organization's prepaid-credit balance

Returns the organization's current prepaid-credit ledger balance, denominated in the organization's own billing currency (`organization.currency`).