Read the account and choose an eligible plan
data.billing_account_id, data.can_manage and data.provider_environment. effect_scope is billing_account_shared. Credential livemode selects business data elsewhere; it does not select the account billing environment. Staging always uses sandbox billing. Production follows the canonical account billing configuration.
The summary includes the current plan, credits and available usage counters. A null counter means unavailable, not zero. Subscription reads return at most 100 subscriptions and expose subscriptions_has_more. Eligible plans follow the same hidden-plan and team-volume rules as the app. Use a returned plan ID and version; do not submit a Stripe price ID. Price and invoice amounts use minor units.
Start checkout with an operation ID
Generate and save a new UUID v4 before sending a change. This lets you read the same operation if the connection drops. Keep its team, account, provider environment and exact request together; do not log credentials, fiscal input or hosted payment URLs.PLAN_FROM_LIST with an eligible plan. An optional plan_version must still be current. intro: true cannot be combined with trial_id; actual eligibility is checked by the server. Free and free-plus plans accept monthly billing only. Accounts on pricing v3 cannot use legacy checkout or upgrade.
Inspect data.status and data.result. A handoff_ready operation with result.kind: "checkout" provides a hosted URL for the person to finish payment. Receiving this URL does not mean the plan changed. Some free-plan changes can complete without a hosted checkout.
The account holds one billing write lock per provider environment. An open checkout keeps that lock until completion or expiry is confirmed. Sending the same operation ID and identical parameters reads the existing operation without replaying the write. Reusing an ID with different parameters returns a conflict.
Read back an uncertain or pending change
handoff_ready. A failed or outcome_unknown result is unsuccessful even when the HTTP response is 200. After a timeout or billing_result_unconfirmed, read this original operation before deciding the next action; do not automatically create a new operation ID and retry.
Operation timestamps are milliseconds. Provider subscription, invoice and checkout dates are seconds. After ten minutes, an unresolved processing operation reads as outcome_unknown. A signed-in Firebase billing administrator can explicitly acknowledge unconfirmed effects and release its lock through POST /operations/{id}/resolve. This preserves the unknown outcome and permits a new operation; it does not cancel, roll back or prove absence of the old effect. Personal MCP credentials cannot perform this browser recovery.
Cancel an abandoned checkout
To expire an open checkout, generate a different UUID v4 and send it asoperation_id to POST /operations/{original_checkout_operation_id}/cancel. Read and reconcile the new cancellation operation ID afterward. This is available to current billing administrators using a verified personal credential.
A confirmed expiry completes the cancellation and makes the original checkout cancelled, with its hosted URL removed. If checkout already completed, cancellation fails with checkout_already_completed and the original becomes completed; manage the subscription through the billing portal. During an uncertain cancellation, the original reads as unknown and points to the cancellation operation. Do not reuse the old checkout link or retry expiry automatically.
Change a subscription or payment method
POST /upgrade accepts a new operation_id, eligible plan_id, billing_cycle, and optional quantity. It requires exactly one manageable subscription and preserves the existing proration behavior. Inspect the operation result and read the account summary afterward.
POST /portal accepts a new operation_id and one intent:
The result is a hosted handoff, not confirmation that the task happened. Creating the portal link releases the billing write lock. Return URLs are configured by the application; callers cannot supply an arbitrary redirect.
Read invoices and update fiscal details
GET /history?limit=20 returns invoices at data.data, with data.has_more and data.cursor. Pass the cursor back unchanged. It is bound to the account, provider environment and customer. Hosted invoice/PDF URLs are sensitive; show them only to the intended user.
GET /fiscal returns the current billing fiscal profile. This read does not repair local mirrors or synchronize Stripe. stripe_synced: null means no synchronization was attempted.
PATCH /fiscal accepts a new operation_id and a fiscal object containing legal_name, rfc, tax_system, use, and address.zip (five digits). Optional email, phone and address fields can be cleared with null. Existing SAT validation still applies. Inspect the operation result: stripe_synced: false means local fiscal data may have been saved while provider synchronization failed. Reconcile and read back before retrying.
Troubleshooting
These contracts are covered by offline validation. Provider and deployment verification must use the intended environment and records authorized for that run.