Start a hosted checkout to upgrade a key

The API key to upgrade. May be sent as an Authorization: Bearer header instead, which wins if both are present.

How often the subscription bills. Omit for monthly — the field is optional precisely so every integration written before annual prices existed keeps working unchanged. An annual price that this deployment does not sell is refused with 400 bad_request; it is never silently downgraded to the monthly price.

Paddle-hosted checkout page. Send the customer here. Nothing is charged until they complete it, and an abandoned one is never billed.

The Paddle transaction this checkout will settle (txn_…). Useful for correlating a support question with a Paddle dashboard row; it is not a credential and grants nothing.

The billing period this checkout was created for. Echoed back even when the request omitted it, so a caller never has to infer what it just created.

The ROUTE that mints a billing-portal link — not a link. Always /v1/billing/portal. Call it with the customer's own key and it returns a one-time URL where they change plan, update the card, download invoices and cancel.

It is an endpoint rather than a URL because Paddle has no static portal page: each link is a session bound to one customer and it expires, so there is nothing durable to publish here, and minting one on every /v1/usage poll would spend a live API call on a link nobody opens.

Present on /v1/usage only for keys that actually have a subscription — a free key has nothing to manage, and pointing one at a route that will answer 409 is worse than saying nothing. Absent, never null.