Billing APIs

Why This Exists

This document defines API responsibilities for the Billing Domain. It does not define final OpenAPI specifications.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Billing APIs provide controlled access to subscription, invoice, payment, entitlement, usage, renewal, and cancellation workflows.

API Groups

API group	Responsibilities	Example endpoints
Billing Account API	Create and manage billing accounts.	POST /billing/accounts, GET /billing/accounts/{accountId}
Plan API	Retrieve plans and plan limits.	GET /billing/plans, GET /billing/plans/{planCode}
Subscription API	Create, change, retrieve, and manage subscriptions.	POST /billing/subscriptions, POST /billing/subscriptions/{subscriptionId}/change-plan
Trial API	Start and inspect trials.	POST /billing/trials, GET /billing/trials/{trialId}
Entitlement API	Retrieve entitlements for access decisions.	GET /billing/subscriptions/{subscriptionId}/entitlements
Usage API	Record and evaluate usage against limits.	POST /billing/usage, GET /billing/subscriptions/{subscriptionId}/usage
Invoice API	Retrieve and manage invoices.	GET /billing/invoices, GET /billing/invoices/{invoiceId}
Payment API	Start payment attempts and inspect payment state.	POST /billing/payments, GET /billing/payments/{paymentId}
Payment Callback API	Process provider callbacks.	POST /billing/providers/{provider}/callbacks
Payment Failure API	Inspect and manage recovery workflow.	GET /billing/payment-failures, POST /billing/payment-failures/{failureId}/retry
Renewal API	Retrieve and manage renewal state.	GET /billing/subscriptions/{subscriptionId}/renewal
Cancellation API	Request or inspect cancellation.	POST /billing/subscriptions/{subscriptionId}/cancel, GET /billing/cancellations/{cancellationId}

API Design Rules

• Subscription changes must go through Billing commands.
• Provider callbacks must be validated and deduplicated.
• Entitlement APIs should be optimized for platform access decisions.
• Notification delivery must be requested through Notification, not sent directly by Billing unless later architecture explicitly defines a provider boundary.
• Final endpoint schemas will be defined in later OpenAPI work.

Example Payment Failure Flow

sequenceDiagram
    participant Provider as Payment Provider
    participant BillingAPI as Billing API
    participant Billing
    participant Notification
    participant Platform

    Provider->>BillingAPI: Payment failed callback
    BillingAPI->>Billing: Validate and deduplicate
    Billing->>Billing: Record payment failure
    Billing->>Notification: Request payment failed notification
    Billing->>Platform: Update entitlement if policy applies