Billing
Generated from
openspec/specs/billing/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”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.
Requirements
Section titled “Requirements”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
generationcredits in their active org requests an AI asset generation - THEN the API returns 402
insufficient_creditsand 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: trueon thechatpool and zerochatBalancesends 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.
Scenario: Pack purchase grants both pools
Section titled “Scenario: Pack purchase grants both pools”- WHEN the webhook receives
checkout.session.completedfor a completed one-off credit-pack session with{ userId, organizationId, packId, generation, chat }metadata - THEN the corresponding (user, org) credit account’s
generationBalanceandchatBalanceeach increase by the pack’sgenerationandchatamounts, 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.completedevents 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_succeededfor an invoice tied to a vendor org’s active subscription - THEN the vendor’s catalogue remains published and the org’s
generationbalance 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.completedfor 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.
Scenario: Unauthorized caller is rejected
Section titled “Scenario: Unauthorized caller is rejected”- WHEN an authenticated user without the
adminorsalesrole requestsPOST /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 × unitAmountCentsacross all lines, persists it with statusopen, 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.
Scenario: Payment marks the invoice paid
Section titled “Scenario: Payment marks the invoice paid”- WHEN the webhook receives
invoice.payment_succeededfor an invoice tagged with sales-invoice metadata - THEN the matching
sales_invoicesrow’s status is set topaid
Scenario: Dashboard void is mirrored locally
Section titled “Scenario: Dashboard void is mirrored locally”- WHEN the webhook receives
invoice.voidedfor a sales invoice that was voided directly in the Stripe dashboard (not through the app’s void endpoint) - THEN the matching
sales_invoicesrow’s status is set tovoid
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_invoicesrow status is set tovoidin 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_KEYset - THEN the endpoint returns a service-unavailable error and performs no Stripe or ledger operation