Skip to main content
MCP billing uses the same order, payment, and subscription rules as the application. The authenticated account determines ownership and available offers. Select product and price IDs from the current catalog.
prepare_billing_action executes a purchase or subscription change. A saved payment method may be charged immediately, and subscriptions can authorize future renewals. It is not an estimate-only operation. Obtain the user’s authorization for the selected purchase before calling it.

​
list_billing_products

Arguments: {}. Reads active paid consumer offers available to the account and country without creating a payment. Returns products and amountUnit: "currency_minor_unit". Each offer contains: A null purchaseAmount means the estimate is unavailable or inapplicable; it does not remove the offer. Discounts and the final payable amount are calculated when the shared payment service executes the action. Do not equate an estimate with the final charge.

​
get_billing_account

Arguments: {}. Returns subscriptions from owned current subscription items. Each entry contains subscriptionId, status, productId, priceId, quantity, nullable effectiveAt, and nullable expiresAt. Dates are Unix timestamps in seconds.

​
prepare_billing_action

purchase_one_time requires a one-time offer. Subscription operations require a recurring offer. upgrade_subscription requires one owned current subscription item; the shared service decides permitted upgrades, downgrades, replacements, proration, and billing-cycle changes. After the user approves the purchase, replace the synthetic catalog IDs below with a matching current product and price:
The receipt contains requestId, operation, orderId, isNewOrder, paymentStatus, immediateCharge (an integer charge amount), chargeInCurrency, and status. Payment status can be success, partial_success, or failure. If payment needs Checkout, it also returns checkoutSessionId, checkoutUrl, expiresAt (Unix seconds), and status: "awaiting_payment". Open the returned Checkout URL and use get_billing_action to read its synchronized status.
requestId is not an idempotency key. Repeating the action, even with the same UUID, executes the service again and may charge again. On an uncertain result, reconcile with support before another purchase. Payment success alone does not prove credits or subscription entitlements have been fulfilled.

​
get_billing_action

Required: nonblank owned checkoutSessionId, at most 200 characters, without surrounding whitespace. Reads synchronized Checkout/webhook records; it does not create a purchase or charge. Returns checkoutSessionId, status, checkoutStatus, paymentStatus, paymentReceived, fulfillmentStatus: "managed_by_webhooks", and orderId when linked. status can be: payment_received and paymentReceived: true confirm the recorded payment state, not entitlement fulfillment. Check the account’s subscription/credits through the application after fulfillment. Immediate-charge actions without a Checkout session have no Checkout status to poll.

​
Billing failures

Errors include INVALID_ARGUMENTS, BILLING_PRODUCT_UNAVAILABLE, BILLING_UPGRADE_UNSUPPORTED, BILLING_ACTION_NOT_FOUND, BILLING_ACTION_UNCONFIRMED, and BILLING_REQUEST_FAILED. Do not automatically retry billing mutations, including after a failed or uncertain response. Read-only catalog/account/Checkout lookups can be repeated without purchasing.