SaaS Billing Reference

This reference describes billing resources, fields, and handling rules for monthly or yearly SaaS integrations. Use the paths, schemas, and scopes provided by the current Application's API product when making calls.

Current capability status

Capability	Status
Fixed monthly/yearly SaaS plan rules	Defined
Application, API access, and Webhook requests	Available through the Developer Console
Commerce Checkout Sandbox API Product	Implemented; callable after it is issued to the Application
Production API Product	Not available
Stored value, usage, and overage billing	Not supported by the current commercial plan

Resources and usage

Resource	Entry point or method	Integration usage
Application, API product, API access grant, Webhook subscription	Developer Console	Request access and get version-specific API configuration
Product/Plan/PriceVersion, Order, SaaSSubscription	Customer workspace	View and manage commercial resources; third parties query necessary state through authorized APIs
Payment, refund, and payment status	Customer workspace	Complete payment or refunds; third parties query redacted state through authorized APIs
ProductAccess, Entitlement	Product access snapshot is not available	Process events under the published contract; do not use internal readback APIs
Payment/refund evidence	Authorized payment-state APIs	Query redacted state and evidence references
Card or wallet credentials	Payment provider	Process only through Hosted Checkout or tokenization

Public fields

These fields apply only to a future issued server-side API or event contract. They are not customer-workspace query parameters. The current commercial-page entry accepts no business parameter or handoff token from a third party.

Field	Constraint
application_code	Derived from the Application and server session; the browser cannot override it
plan_code / plan_version	Identify an approved plan and immutable version
price_version_ref	Identifies an immutable price snapshot and is not generated by the browser
billing_interval	Only month or year
amount_scaled / amount_scale	Integer amount and scale derived from the server-side price snapshot
currency	Uppercase ISO 4217 code determined by the plan/order
operation_id	Unguessable asynchronous operation identifier, not a payment credential
resource_version	Monotonically increasing per resource for out-of-order event protection

Interpret an amount as amount_scaled × 10^-amount_scale. For example, 2900 with scale 2 means 29.00. Do not calculate or transmit money as floating-point values.

Request requirements

1. Browsers never hold a server OAuth Client Secret, Webhook Secret, or payment credential.
2. A third-party browser only opens the platform customer workspace. It submits no plan, amount, currency, tenant, provider, or arbitrary return URL.
3. Only the controlled customer-workspace BFF creates Checkout with a stable Idempotency-Key.
4. A browser return does not prove payment success; final status comes from a verified provider notification or server reconciliation.
5. After payment, confirm subscription and ProductAccess state separately before enabling product features.
6. The current commercial plan records subscription payment and refund evidence only; it accepts no stored-value, usage, or overage fields.

Expected API Product composition after publication

Capability group	Typical operations
Catalog	List monthly/yearly plans available to the current Application
Subscription	Read subscription summary, schedule cancellation, resume, or change plan
Checkout	Create Hosted Checkout and read asynchronous Operation status
Billing	Read redacted payment/refund evidence and status
Access	Product access snapshot requires a separate release and cannot currently be called
Events	Subscribe to lifecycle, payment/refund result, and access events

Sandbox Commerce Checkout provides product catalog, Checkout Session, Operation query, subscription query, cancellation and plan-change APIs. Amounts use published USD prices.

• Writes require Idempotency-Key.
• Cancellation and plan changes set If-Match using the current resource_version.
• The platform verifies provider callbacks and delivers redacted payment/refund events through approved Webhook subscriptions. Third parties do not call payment callback endpoints.

Before Production opens, Developer Console will provide API Product versions, Base URL, Audience, scopes, OpenAPI/AsyncAPI and deprecation guidance.

After login, User and customer space provides public user aliases and the current space. Correlate subscriptions by Application, environment, customer space and subscription ID. User context does not grant paid or product permissions. See Applications, users and events and Product access snapshot.

Safe browser fields

A third-party frontend receives only minimal ProductAccess state and server-configured platform entries. Plan display data, a redacted payment method, short-lived Checkout URL, Operation status, and payment/refund evidence summaries are rendered only in the platform customer workspace. No frontend may receive a full card number, CVC, chargeable token, provider secret, Webhook Secret, internal route, or platform audit data.