Skip to content

Billing

Generated from openspec/specs/billing/spec.md — edit that file, not this page.

Provide Stripe-backed monetization for Tinkerspace: one-off AI-credit purchases, a recurring vendor catalogue subscription, vendor ad-wallet top-ups, and ad-hoc sales invoices — all fulfilled through a single Stripe webhook so that payment confirmation is idempotent and centrally auditable.

Requirement: Metered AI actions are gated by per-(user, org) credit balances

Section titled “Requirement: Metered AI actions are gated by per-(user, org) credit balances”

The system SHALL require a positive credit balance in the relevant pool (generation or chat) before performing a metered AI action, SHALL charge the balance of the caller’s currently active organization, and SHALL refund the charge if the downstream provider call subsequently fails.

Scenario: Insufficient balance blocks the action

Section titled “Scenario: Insufficient balance blocks the action”
  • WHEN a user with zero generation credits in their active org requests an AI asset generation
  • THEN the API returns 402 insufficient_credits and does not call the generation provider

Scenario: Provider failure after a successful charge is refunded

Section titled “Scenario: Provider failure after a successful charge is refunded”
  • WHEN a credit charge succeeds but the downstream provider call then fails
  • THEN the API refunds the charge back to the same (user, org) credit account it debited

Scenario: Switching active org switches the charged balance

Section titled “Scenario: Switching active org switches the charged balance”
  • WHEN a user with credits in org A switches their active organization to org B and performs a metered action
  • THEN the action is charged against org B’s balance for that user, not org A’s

Requirement: Platform admins and unlimited accounts bypass metering

Section titled “Requirement: Platform admins and unlimited accounts bypass metering”

The system SHALL allow platform-admin callers and accounts flagged unlimited for a given pool to perform metered actions without consuming or requiring any credit balance.

Scenario: Unlimited account performs an action with zero balance

Section titled “Scenario: Unlimited account performs an action with zero balance”
  • WHEN an account with unlimited: true on the chat pool and zero chatBalance sends a chat prompt
  • THEN the request succeeds and no credit balance changes

Requirement: A completed credit-pack purchase tops up the buyer’s balances

Section titled “Requirement: A completed credit-pack purchase tops up the buyer’s balances”

The system SHALL, on a successfully completed one-off credit-pack Checkout session, grant that pack’s credit amounts to the purchasing (user, organization) account without clamping to any quota ceiling.

  • WHEN the webhook receives checkout.session.completed for a completed one-off credit-pack session with { userId, organizationId, packId, generation, chat } metadata
  • THEN the corresponding (user, org) credit account’s generationBalance and chatBalance each increase by the pack’s generation and chat amounts, uncapped by the account’s quota

Requirement: Purchase and invoice fulfilment is idempotent

Section titled “Requirement: Purchase and invoice fulfilment is idempotent”

The system SHALL fulfil each Checkout session or paid invoice at most once, even if Stripe delivers the same webhook event more than once.

Scenario: Duplicate webhook delivery does not double-grant

Section titled “Scenario: Duplicate webhook delivery does not double-grant”
  • WHEN the webhook receives two checkout.session.completed events for the same Checkout session id (a Stripe retry)
  • THEN credits are granted only on the first delivery and the second delivery grants nothing

Requirement: A paid vendor subscription invoice keeps the catalogue published and grants credits

Section titled “Requirement: A paid vendor subscription invoice keeps the catalogue published and grants credits”

The system SHALL, on each successfully paid vendor subscription invoice, keep the vendor organization’s catalogue publishable past its freemium window and grant that organization’s generation credit pool a fixed top-up.

Scenario: Recurring payment extends publication and grants credits

Section titled “Scenario: Recurring payment extends publication and grants credits”
  • WHEN the webhook receives invoice.payment_succeeded for an invoice tied to a vendor org’s active subscription
  • THEN the vendor’s catalogue remains published and the org’s generation balance increases by the vendor subscription’s fixed credit grant, idempotently per invoice id

Requirement: A lapsed vendor subscription unpublishes the catalogue

Section titled “Requirement: A lapsed vendor subscription unpublishes the catalogue”

The system SHALL detect a vendor subscription that is no longer active and unpublish that vendor’s catalogue.

Scenario: Cancelled subscription mirrors to unpublished status

Section titled “Scenario: Cancelled subscription mirrors to unpublished status”
  • WHEN Stripe reports a vendor’s subscription as canceled via customer.subscription.deleted, and the vendor does not renew before the next scheduled lapse check
  • THEN the vendor’s catalogue is no longer published

Requirement: Ad wallet top-ups credit the paying organization’s ad wallet

Section titled “Requirement: Ad wallet top-ups credit the paying organization’s ad wallet”

The system SHALL, on a completed ad-wallet top-up Checkout session, credit the purchasing organization’s ad wallet balance by the paid amount in cents.

Scenario: Ad top-up increases wallet balance

Section titled “Scenario: Ad top-up increases wallet balance”
  • WHEN the webhook receives checkout.session.completed for a session whose metadata marks it as an ad wallet top-up for a given organization
  • THEN that organization’s ad wallet balance increases by the session’s paid amount in cents

Requirement: Sales invoice creation is restricted to authorized roles

Section titled “Requirement: Sales invoice creation is restricted to authorized roles”

The system SHALL allow only callers with the admin or sales platform role to create, list, or void ad-hoc sales invoices, and SHALL reject all other callers.

  • WHEN an authenticated user without the admin or sales role requests POST /admin/invoices
  • THEN the request is rejected and no Stripe invoice is created

Requirement: An authorized caller can generate an ad-hoc sales invoice

Section titled “Requirement: An authorized caller can generate an ad-hoc sales invoice”

The system SHALL let an authorized caller compose a customer and one or more free-form SGD line items into a finalized Stripe hosted invoice, and SHALL return its hosted payment URL and PDF link.

Scenario: Valid payload produces a payable hosted invoice

Section titled “Scenario: Valid payload produces a payable hosted invoice”
  • WHEN an admin or sales caller submits a valid payload (customer name, valid email, at least one line item with quantity ≥ 1 and unit amount ≥ 50 cents, a due window of 1–90 days, and a payment-method selection drawn from card/PayNow/GrabPay)
  • THEN the system creates and finalizes a Stripe invoice for the sum of quantity × unitAmountCents across all lines, persists it with status open, and returns its hosted invoice URL and PDF link

Scenario: Invalid payload is rejected before any Stripe call

Section titled “Scenario: Invalid payload is rejected before any Stripe call”
  • WHEN a caller submits a payload with an empty line-item list, a quantity below 1, a unit amount below 50 cents, an invalid customer email, a due window outside 1–90 days, or a payment method outside card/PayNow/GrabPay
  • THEN the request is rejected and no Stripe invoice is created

Requirement: Sales invoice payment status is mirrored idempotently from Stripe

Section titled “Requirement: Sales invoice payment status is mirrored idempotently from Stripe”

The system SHALL keep a sales invoice’s stored status synchronized with its Stripe lifecycle: paid when Stripe reports successful payment, void or uncollectible when Stripe reports either outcome — without requiring a separate deduplication record, since each update is an idempotent status set keyed by the Stripe invoice id.

  • WHEN the webhook receives invoice.payment_succeeded for an invoice tagged with sales-invoice metadata
  • THEN the matching sales_invoices row’s status is set to paid

Scenario: Dashboard void is mirrored locally

Section titled “Scenario: Dashboard void is mirrored locally”
  • WHEN the webhook receives invoice.voided for a sales invoice that was voided directly in the Stripe dashboard (not through the app’s void endpoint)
  • THEN the matching sales_invoices row’s status is set to void

Scenario: App-initiated void updates both Stripe and the local record

Section titled “Scenario: App-initiated void updates both Stripe and the local record”
  • WHEN an authorized caller voids an open sales invoice through the app’s void endpoint
  • THEN the invoice is voided in Stripe and the local sales_invoices row status is set to void in the same request

Requirement: Billing routes fail soft when Stripe is unconfigured

Section titled “Requirement: Billing routes fail soft when Stripe is unconfigured”

The system SHALL respond to any billing-related request with a service- unavailable error, rather than an unhandled crash, when no Stripe secret key is configured for the running environment.

Scenario: Checkout request without a configured Stripe key

Section titled “Scenario: Checkout request without a configured Stripe key”
  • WHEN a request reaches any billing endpoint (credit checkout, vendor billing, ad wallet top-up, or sales invoices) in an environment with no STRIPE_SECRET_KEY set
  • THEN the endpoint returns a service-unavailable error and performs no Stripe or ledger operation