Skip to main content

Billing

πŸ“„οΈPlan, subscription

Plan, subscription (`paid_by`: card | bank_transfer), current period (included / used / from credit / overage), prepaid credit, headroom, spending limit, hold, plans, credit pack range and Paddle.js settings (client token, environment). A client workspace billed to its agency gets `billed_to_agency` { agency_id, agency_name, spending_cap_usd, usage_usd, cap_left_usd }, the agency's plan, `can_manage: false` and no agency subscription/credit details; its billing writes (checkout, credit, plan, spending limit, bank transfer) answer 409 `{billed_to_agency: true}`

πŸ“„οΈWhat a plan or interval change does, before confirming

What a plan or interval change does, before confirming. mode `now` (an upgrade, or any change in a trial): Paddle's prorated amounts β€” new_plan_amount (the new plan for the rest of the period), unused_credit (the unused part of the old plan), tax, result_action charge | credit and result_amount (tax in); covered: true when Paddle was already paid for the target plan (or a higher one) in the current billing period, same interval and not yet ended (an upgrade back after a downgrade), so it applies unbilled (do_not_bill) until the next renewal. mode `scheduled` (a downgrade: a lower plan, or year β†’ month): nothing is charged now and the change takes effect at effective_at, the end of the paid period

πŸ“„οΈAutomatic top-up

Owner/admin: automatic top-up. When prepaid credit drops below `below_usd`, a one-time charge of `amount_usd` (plus tax) on the subscription's card buys more; the credit lands with Paddle's webhook, and no second top-up is sent before it does. Saving it while credit is already below `below_usd` sends the first top-up at once, on the queue: the answer shows it as pending at most, so poll GET /billing for the outcome (credit landed, `enabled: false` with `error` when declined, `pending_usd` with `error` when unconfirmed). A declined card turns it off and notifies the account. Saving clears the last `error`/`paused`, unless a top-up is still pending. `below_usd: null` turns it off. An approved refund or chargeback turns it off too. GET /billing returns the state as `auto_topup` { enabled, below_usd, amount_usd, pending_usd, last_at, error, paused: { action: refund | chargeback, invoice } | null, available }