Plans & billing

Most customers manage their plan in the dashboard (Plan). The endpoints below are what the dashboard uses; you only need them to build your own billing UI.

Plans and terms

Every plan includes every currency, every endpoint and the MCP server; plans differ only in volume. Pay monthly, or for 3, 6 or 12 months — longer terms are discounted, and the discount applies to the whole term. The quota is always monthly (see billing periods).

You can pay in two ways, with the same discount:

	Subscription	One-time payment
Renews	automatically every term	never
Change plan	any time, prorated	buy another term
Cancel	at the end of the paid period, can be undone	nothing to cancel
Buying again	—	the same plan extends your term

An account is either subscribed or prepaid, not both. When a prepaid term ends, the account returns to Free automatically.

Payments are processed by Stripe; card details never reach GetRatesAPI.

Price list

GET /v1/pricing — public, no authentication. Prices are integer cents of currency; monthly_price_cents is null for plans sold by contract (Enterprise).


curl https://your-getratesapi-host/v1/pricing


{
  "currency": "usd",
  "terms": [
    { "months": 1, "discount_percent": 0, "enabled": true },
    { "months": 3, "discount_percent": 5, "enabled": true },
    { "months": 6, "discount_percent": 10, "enabled": true },
    { "months": 12, "discount_percent": 20, "enabled": true }
  ],
  "plans": [
    {
      "code": "developer",
      "name": "Developer",
      "description": "Side projects and internal tools.",
      "monthly_price_cents": 1200,
      "request_unit_quota": 50000,
      "requests_per_second": 10,
      "highlighted": false,
      "self_serve": true
    }
  ]
}

(plans is shortened here.) Term total = monthly price × months × (1 − discount), rounded half-up to a whole cent: Developer for 12 months at 20 % is 1200 × 12 × 0.8 = 11520 cents.

Current plan

GET /v1/account/billing (Session required):


{
  "plan_code": "developer",
  "pending_plan_code": null,
  "status": "active",
  "cancel_at_period_end": false,
  "current_period_start": "2026-10-16T18:37:48Z",
  "current_period_end": "2026-11-16T18:37:48Z",
  "billing_mode": "subscription",
  "prepaid_until": null,
  "term_months": 1,
  "has_billing_account": true
}

billing_mode is free, subscription or prepaid.

Paying

GET /v1/billing/config (public) returns {"enabled": true, "publishable_key": "pk_test_…", "test_mode": true} for Stripe.js.
POST /v1/account/payments (Session required) with {"plan": "developer", "months": 12, "mode": "subscription"} — mode is subscription or one_time. The 201 response contains the payment id, amount_cents, discount_percent and a client_secret.
Confirm the client_secret with the Stripe Payment Element .
POST /v1/account/payments/{id}/sync (no body) — the API re-reads the payment from Stripe and activates the plan once it is paid. Poll until status is paid.

On a running subscription, step 2 changes the plan or term; Stripe prorates the difference and may return no client_secret when nothing is due.

`409` code	Meaning
`subscription_active`	One-time payment while subscribed — change the subscription instead
`prepaid_active`	Subscribing while a prepaid term runs
`prepaid_downgrade`	Buying a lower plan while a higher prepaid term runs
`subscription_payment_issue`	Fix the payment method first
`already_subscribed`	Same plan and term as today

400 invalid_plan means an unknown plan, a term that is not offered, or a plan that is not sold online (Free, Enterprise).

Invoices, cancel and resume

Method	Path	Notes
`GET`	`/v1/account/invoices`	Up to 24 invoices with `invoice_pdf` and `hosted_invoice_url`
`POST`	`/v1/account/subscription/cancel`	Ends the subscription at the end of the paid period. No body
`POST`	`/v1/account/subscription/resume`	Withdraws a scheduled cancellation. No body
`POST`	`/v1/account/billing-portal-session`	Link to update the card and billing details. No body

Cancel and resume return 409 no_subscription when there is nothing to change. Billing that is not configured on a server returns 503 billing_disabled.