> ## Documentation Index
> Fetch the complete documentation index at: https://developers.apob.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing tools

> Read available products and subscriptions, execute purchases, and reconcile Checkout status.

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.

<Warning>
  `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.
</Warning>

## 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:

| Field | Meaning |
| - | - |
| `productId`, `priceId`, `name` | Identifiers and product name. |
| `type` | `one_time` or `recurring`. |
| `unitAmount`, `currency` | Full price in currency minor units and currency code. |
| `purchaseAmount` | Nullable pre-discount remaining-period yearly upgrade estimate. |
| `interval`, `intervalCount` | Nullable recurring period; eligible recurring offers use `month` or `year`, count `1`. |
| `creditGrants` | Array of `{ "category": ..., "amount": ... }` credit grants. |

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.

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 30,
  "method": "tools/call",
  "params": { "name": "list_billing_products", "arguments": {} }
}
```

## 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

| Input | Required | Contract |
| - | - | - |
| `operation` | Yes | `subscribe`, `upgrade_subscription`, or `purchase_one_time`. |
| `productId`, `priceId` | Yes | Nonblank IDs from `list_billing_products`, at most 200 characters each, without surrounding whitespace. |
| `requestId` | Yes | Canonical lowercase UUID, exactly 36 characters, used for correlation. |
| `quantity` | No | Integer `1`; default `1`. All operations require one unit. |

`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:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 31,
  "method": "tools/call",
  "params": {
    "name": "prepare_billing_action",
    "arguments": {
      "operation": "purchase_one_time",
      "productId": "example-product-id",
      "priceId": "example-price-id",
      "quantity": 1,
      "requestId": "11111111-2222-4333-8444-555555555555"
    }
  }
}
```

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.

<Warning>
  `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.
</Warning>

## 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:

| Status | Meaning |
| - | - |
| `payment_received` | Checkout records a paid payment. |
| `payment_not_required` | Checkout records no required payment. |
| `expired` | An unpaid Checkout has expired. |
| `payment_unconfirmed` | Checkout is complete without confirmed payment. |
| `awaiting_payment` | Payment has not completed. |

`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.