--- title: "Billing · API reference · Promigence" description: "The Promigence API's billing routes: 10 in all, with parameters, request bodies and answers." url: "https://www.promigence.ai/docs/reference/api/billing" site: "Promigence" --- [API reference](https://www.promigence.ai/docs/reference/api) # Billing 10 routes of the published API contract, generated from it. ### GET/v1/billing Auth: API key Plan, card on file, this month's usage, and the upcoming invoice preview. #### Answer 200 · BillingStatus · application/json billing_enabledrequiredboolean False while card billing is not available. cardCardOnFile | null `null` while no card is on file. card_notestring | null A sentence to show beside the card when it does not unlock paid limits for this organization (it already pays for another one, or it is being confirmed with a $1 charge, or that charge did not go through); `null` otherwise. card_on_filerequiredboolean customerrequiredboolean True once a billing customer exists for the organisation. method_checkMethodCheckView | null The $1 that confirms the payment method on file when it has no stable payer (Apple Pay, Google Pay, Amazon Pay); `null` when it needed none. noticeTrialNotice | null org_idrequiredstring periodrequiredBillingPeriod The billing period `usage` covers. planrequiredstring suspend_reasonstring | null suspendedrequiredboolean trialrequiredTrialStatus The trial an organisation is on, and what is left of it. upcoming_invoiceUpcomingInvoice | null The payment provider's estimate of the next invoice; `null` when there is no subscription, or when the estimate could not be fetched (see `upcoming_invoice_error`). upcoming_invoice_errorstring | null usagerequiredPeriodUsage What a period cost, by what it was spent on. ### POST/v1/billing/checkout Auth: API key Start a card-setup checkout. Adding a card keeps any trial credit you have left. Owners only (with their own key). #### Answer 200 · CheckoutSession · application/json expires_atstring | null When the link stops working, RFC 3339. moderequiredstring `"setup"` — the checkout stores a card, it does not take a payment. session_idstring | null urlrequiredstring Open this. Adding a card keeps any trial credit that is left. ### GET/v1/billing/history Auth: API key Your billing history, newest first: every credit you received, with what is left of it and when it expires, and every payment (invoices paid, payments that failed, refunds). `kind` is `all` (the default), `credits` or `payments`; `limit` is up to 100 (50 by default); pass `next_cursor` back as `cursor` for older entries. Owners only (with their own key). #### Parameters cursorquery · string kindquery · string limitquery · integer #### Answer 200 · BillingHistory · application/json entriesrequiredBillingHistoryEntry[] next_cursorstring | null Pass as `cursor` for the next, older page; `null` on the last page. ### POST/v1/billing/portal Auth: API key A link to the billing portal. Owners only (with their own key). #### Answer 200 · PortalSession · application/json urlrequiredstring ### POST/v1/credits/claim Auth: none The claim the page sends: the link's token, the accepted terms version and the page's browser check. Answers the credit as it now stands: claimed, being checked (usually under 24 hours), or why there is none. Rate limited per address. #### Request body CreditClaim · application/json · optional accept_termsboolean browserstring | null powstring | null terms_versionstring | null tokenstring | null #### Answer 200 · CreditOffer · application/json campaignstring | null The giveaway this credit comes from, when it does. card_bonus_usdrequirednumber USD a first card would add, while it still would. credit_usdrequirednumber USD: what a claim gives now (`claimable`) or gave (`claimed`). expires_atstring | null When the credit expires (RFC 3339), when it does. messagerequiredstring One sentence for a person. method_check_usdnumber USD charged to confirm a payment method with no stable payer when it is added (Apple Pay, Google Pay, Amazon Pay): it is added to your credit, and the card bonus comes with it. staterequiredstring `claimable`, `claimed`, `pending_review`, `needs_card`, `not_eligible`, `offer_ended`, `denied` or `none`. ### POST/v1/credits/claim-link Auth: API key A single-use link (15 minutes) to the page where the free credit is claimed (`promigence credits claim` opens it). A service key cannot ask for one. `409` with the reason when there is nothing to claim. #### Answer 200 · ClaimLink · application/json expires_atrequiredstring RFC 3339. urlrequiredstring Open it in a browser. It works once, for 15 minutes. ### GET/v1/credits/offer Auth: API key Your account's free credit: claimable (and how much, until when), claimed, being checked, needs a card, or none. The credit is claimed in a browser, never with an API call alone. #### Answer 200 · CreditOffer · application/json campaignstring | null The giveaway this credit comes from, when it does. card_bonus_usdrequirednumber USD a first card would add, while it still would. credit_usdrequirednumber USD: what a claim gives now (`claimable`) or gave (`claimed`). expires_atstring | null When the credit expires (RFC 3339), when it does. messagerequiredstring One sentence for a person. method_check_usdnumber USD charged to confirm a payment method with no stable payer when it is added (Apple Pay, Google Pay, Amazon Pay): it is added to your credit, and the card bonus comes with it. staterequiredstring `claimable`, `claimed`, `pending_review`, `needs_card`, `not_eligible`, `offer_ended`, `denied` or `none`. ### GET/v1/pricing Auth: API key Your organization's price list, read live on every call from what billing charges: the per-second rates, every sandbox shape on sale and its price (a snapshot build is billed at its tier's), the limits, the free credit and the plan they come from (`scope: organization`). Needs an API key; without one the answer is `auth` (401). The published list prices are on the pricing page and in `promigence pricing` before you sign in. A run is billed at the rates in force when it was created. #### Answer 200 · PricingView · application/json as_ofrequiredstring When these values were read, RFC 3339. They can change at any time: read them again rather than keeping a copy. billingrequiredstring `per_second`: a sandbox bills `(vcpus × vcpu_second_usd + mem_gib × gib_second_usd) × billable seconds`, from hand-over to end, minus paused time. currencyrequiredstring `usd`. free_creditrequiredPricingFreeCredit The free credit a new account gets. An account's own credit, and whether it can still claim it, is `GET /v1/credits/offer`. granularity_secondsrequiredinteger Billable seconds are rounded up to this many. included_credits_usdrequirednumber Usage the monthly fee includes each month, USD. limitsrequiredPricingLimits The limits in force. min_billable_secondsrequiredinteger The fewest seconds a sandbox that ran is billed. monthly_fee_usdrequirednumber The plan's monthly fee, USD. monthly_minimum_usdrequirednumber A committed monthly minimum, USD; 0 for none. org_idrequiredstring The organisation these values are for. planrequiredPricingPlan The plan the prices and limits come from. ratesrequiredPricingRates The rates, USD. schemarequiredstring `promigence.pricing/v1`. scoperequiredstring `organization`: what the key's organisation pays. tiersrequiredPricingTier[] Every sandbox shape on sale, smallest first, priced at these rates. ### GET/v1/referrals Auth: API key Your referral code and its offer ("Give $X, get $Y"), your referrals by status, what they earned you, the referral you came through, and your credit that expires. The code exists while an offer runs. #### Answer 200 · ReferralStatus · application/json codestring | null Your code: a friend signs up with `promigence login --ref `. `null` while the program is off. earned_usdrequirednumber Credit your referrals have earned you, USD. expiring_creditsrequiredExpiringCredit[] Credit that expires, soonest first, with what is left of each grant. offerReferralOffer | null What your code offers now. `null` while the program is off. programrequiredstring `"on"` while an offer runs, else `"off"` (no code is handed out then). referralsrequiredReferralCounts Your referrals by status (counts only). referred_byReferredBy | null The referral this organization came through, if any. ### POST/v1/referrals/apply Auth: API key Apply a referral code to your organization: before its first paid invoice and within the offer's window after the organization was created. The credit comes with your first paid plan invoice. Owners only (with their own key). Body: `{code}`. #### Request body ReferralApply · application/json coderequiredstring The referral code, at most 64 characters. #### Answer 200 · ReferralApplied · application/json coderequiredstring detailstring | null Why the code was not applied (`not_applied` only). qualifying_plansrequiredstring[] Plans that invoice qualifies on; empty = any paid plan. reward_usdrequirednumber Compute credit this organization gets when it pays its first plan invoice, USD. statusrequiredstring `pending` (your credit comes with your first paid plan invoice), `under_review`, or — at sign-in only — `not_applied`. [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors)