Billing

Endpoint	What it does
GET /plans	Available plans and their limits. No token needed.
GET /subscription	The current subscription (with renewalDate, and pendingPlanId when a move to Free waits for the paid month to end), billedBy (web, store, or null on Free and Enterprise), billingStore (which store, when one bills the plan), storeRenewing (whether that store will charge again), storePurchaseFrom (null when the apps may sell a plan through the App Store or Google Play, otherwise the end of a month already paid for on the web), storeSwitchAt (when a move to store billing was asked for, or null), currentPriceMinor (what the account pays for its current plan, which may be a negotiated price rather than the list price), the account balance as balanceMinor and the part of it you paid in as paidBalanceMinor, and pause after a missed payment.
POST /subscription/plan	Change plan with a planId. If the balance covers the plan’s price, the month is paid from it straight away, up or down. Otherwise an upgrade returns 402 payment_required and goes through checkout. Moving to Free during a paid month keeps the plan until renewalDate and sets pendingPlanId; sending the current planId again cancels that. Moving between two paid plans during a paid month also needs a payment. Refused with 409 downgrade_blocked if the account holds more addresses than the plan allows, or more than one device when moving to Free. Enterprise is 400 contact_sales. Session only.
POST /subscription/store-switch	Move a plan paid on the web to App Store or Google Play billing. Its Polar card subscription is cancelled at the end of the month and the balance stops paying for it; the month already paid for runs to its end, and the apps sell the plan from then. If it isn’t bought there, it lapses like any unpaid plan. 409 nothing_to_switch without a month paid on the web still running. 502 provider_error if Polar can’t be reached, and nothing changes. Session only.
DELETE /subscription/store-switch	Keep web billing after all. Starts the Polar card again while the month runs. 409 no_change when no move is waiting. Session only.
GET /billing/providers	Payment methods available, each with its kind (card or crypto) and whether it takes a topUp. Also returns topUp.minMinor and topUp.maxMinor, the range topUpMinor accepts. No token needed.
POST /billing/checkout	Open a hosted checkout with a provider: polar for card or nowpayments for crypto. Send a planId to buy a month of a plan, or topUpMinor to add that many cents to the balance instead. Returns 201 with the checkout url and the pending payment. A provider that is unavailable returns 503 provider_unavailable. At most 20 a day. Session only.
GET /billing/cancellations	Purchases made on the website that you can still cancel within 14 days, and those already cancelled, as items: paymentId, kind (plan or topup), planId, provider, amountMinor, paidAt, windowEndsAt and cancelledAt. Session only.
POST /billing/cancellations	Cancel one of those purchases with its paymentId. Records your notice and returns the cancellation; the refund follows as the Refund Policy sets out. Sending it again changes nothing. 404 not_cancellable for a purchase this does not cover, 409 window_closed after its 14 days, 409 already_refunded once refunded. Session only.
GET /billing/payments/:id	One payment: id, kind (plan or topup), provider, planId, amountMinor, currency, status, createdAt, updatedAt and appliedAt. A plan changes, or the balance goes up, when it is paid.

The balance

The balance is paid in on the web, by card or crypto, with any amount from $15 to $2,000 (topUpMinor from 1500 to 200000). It buys Mailcycle plans and nothing else. It cannot be withdrawn or transferred. The part you paid in and have not spent is refunded only in the cases the Refund Policy lists, which include cancelling a top-up within 14 days and asking before you delete the account.

• Each month the plan takes its price from the balance while the balance covers it.
• The balance is spent before a card. When the plan also has a card subscription and the balance covers the next month, the balance pays for that month and the card is not charged for it. Once the balance can’t cover a month, the card pays in full and the balance is kept.
• While the App Store or Google Play bills the plan, including while it retries a failed charge, the balance pays nothing and POST /subscription/plan and POST /billing/checkout return 409 store_billed.
• When the store subscription ends (cancelled in the store, or the store gave up on a failed charge), the balance pays for the plan again from the date it ended, a month at a time. A Polar card from before the store took over is not charged again; only a new card checkout starts one.

Refunds

There is no refund endpoint. Refunds follow the Refund Policy: an account’s first plan payment made on the website, if asked for within 14 days and nothing the plan adds was used, and, for a consumer, each new plan purchase and each top-up on the website cancelled within 14 days, with POST /billing/cancellations or through support. A crypto payment short of the invoice is refunded whenever asked, less the network fee. Ask through support. A refunded plan ends and the account moves to Free, the same as after a missed payment. Plans bought in the iOS or Android app are refunded by Apple or Google.

The pause object

After a missed payment, GET /subscription includes:

{
  "pause": {
    "planId": "plan_scale",
    "since": "2026-10-19T10:00:00.000Z",
    "deletesAt": "2026-11-09T10:00:00.000Z",
    "addresses": 2,
    "devices": 1,
    "apiKeys": 1,
    "domains": 0
  }
}

planId is the plan to pay for. It is null once paid, if something the new plan does not cover is still paused. pause is null when nothing is paused. See Missed payments.