AI credits

Boxpressd Payments owns shared AI credit balances, entitlement grants, usage reservations, and the credit ledger. Developer applications consume the same credit type through the Developer API and Presston AI MCP. Most developers buy credits through the Developer Dashboard. The service-to-service flow on this page is for approved Boxpressd billing clients.

Authorize the billing account

Clients configured for account assertions must first authorize the signed-in user against the requested resource. The backend signs a short-lived assertion that binds the service client, user, billing role, resource type, resource ID, issuer, audience, issue time, expiry, and unique token ID.

POST /api/v1/billing-accounts/resolve
Authorization: Bearer <service-client-secret>
X-Boxpressd-Client-Id: developer-dashboard
Content-Type: application/json

{ "assertion": "<short-lived-signed-account-assertion>" }

Payments verifies the assertion and returns only the authorized billing account, balance, entitlements, saved-method projection, and purchase information allowed by the billing role. Never send an arbitrary billing-account UUID from the browser and trust it on the backend. Bind the account through the signed assertion.

Discover current offers

Ask Payments for the offers allowed for the client and resource type:

curl --get "https://payments.boxpressd.com/api/v1/offers" \
  --header "Authorization: Bearer $BOXPRESSD_PAYMENTS_CLIENT_SECRET" \
  --header "X-Boxpressd-Client-Id: developer-dashboard" \
  --data-urlencode "resourceType=developer_application"

An offer includes server-owned pricing, resource availability, and effects such as:

{
  "entitlements": [{ "code": "api.ai" }],
  "credits": [{ "type": "ai", "amount": 1000 }],
  "availability": {
    "resourceTypes": ["developer_application"]
  }
}

Do not hard-code pack prices or credit amounts. Render active offers returned for the current resource type.

Create the credit checkout

Create a payment session with the same unexpired billing assertion and the selected server-owned offer code:

curl "https://payments.boxpressd.com/api/v1/payment-sessions" \
  --request POST \
  --header "Authorization: Bearer $BOXPRESSD_PAYMENTS_CLIENT_SECRET" \
  --header "X-Boxpressd-Client-Id: developer-dashboard" \
  --header "Idempotency-Key: credit-checkout-app-123-20260910" \
  --header "Content-Type: application/json" \
  --data '{
    "action": "purchase",
    "actor": { "type": "boxpressd_user", "id": "123" },
    "billingAccountId": "00000000-0000-0000-0000-000000000001",
    "billingAccountAssertion": "<short-lived-signed-account-assertion>",
    "offerCode": "developer-ai-credits-1000",
    "returnUrl": "https://developers.boxpressd.com/dashboard/apps/app_123/ai?payments=returned",
    "cancelUrl": "https://developers.boxpressd.com/dashboard/apps/app_123/ai?payments=cancelled",
    "presentation": "page"
  }'

Use the one-time data.url immediately. After capture, Payments grants the configured entitlement and credits idempotently and queues a signed developer.billing.purchase_fulfilled event for the Developer API.

Configure automatic reload

An approved billing client with billing_accounts:write can configure automatic reload for an assertion-authorized account:

{
  "assertion": "<short-lived-signed-account-assertion>",
  "productCode": "ai-credits",
  "enabled": true,
  "deferInitialReload": true,
  "thresholdCredits": 100,
  "reloadCredits": 1000,
  "monthlyLimitMinor": 5000
}

Send the request to POST /api/v1/billing-accounts/auto-reload. Amounts ending in Minor use the currency’s minor unit.

Usage settlement

Public clients do not create usage reservations directly in Payments. The Developer API reserves a configured ceiling before a paid operation and settles actual provider usage afterward. Settlement accounts for input, cached-input, output, and web-search usage using versioned provider rates. Failed operations release their reservations. Concurrent requests lock the account balance so two requests cannot spend the same credits.

Getting started

Integrate

Credits and billing

Authorize the billing account

Discover current offers

Create the credit checkout

Configure automatic reload

Usage settlement

​Authorize the billing account

​Discover current offers

​Create the credit checkout

​Configure automatic reload

​Usage settlement

Authorize the billing account

Discover current offers

Create the credit checkout

Configure automatic reload

Usage settlement