Billing - ezForge AI

Required scope: billing:read

Get billing status

GET /v1/billing

Returns the current subscription and usage summary. Response 200:

{
  "data": {
    "plan": "developer",
    "status": "active",
    "limits": {
      "servers": 10,
      "requestsPerMonth": null,
      "logRetentionDays": 30,
      "maxDomainMembers": 1,
      "seatPrice": 0
    },
    "features": {
      "team": false,
      "auditLog": false
    },
    "usage": {
      "servers": 3,
      "requestsThisMonth": 0
    },
    "stripeCustomerId": "cus_...",
    "stripeSubscriptionId": "sub_...",
    "currentPeriodStart": "2026-03-01T00:00:00Z",
    "currentPeriodEnd": "2026-04-01T00:00:00Z",
    "cancelAtPeriodEnd": false
  }
}

Plan values: free | starter | developer | pro | scale. Accounts on the legacy enterprise plan are reported as scale. Status values: active | past_due | canceled | trialing | incomplete limits.requestsPerMonth is the published monthly request allotment (enforced only once metering is active). It is a number on free and null on every paid plan. null means the plan has no request cap: requests are metered and bounded by a spend cap instead (see Spend cap). limits.maxDomainMembers is null when the plan has no member-count cap. Extra seats are billed at limits.seatPrice per seat. usage.requestsThisMonth is the request count for the current billing period (the Stripe period when one exists, otherwise the UTC calendar month). Per-request metering is not active yet, so this currently reads 0.

Usage is recorded internally as an hourly total for each server and meter. Recording the same hour again replaces its total rather than adding to it, so retries never double-count, and an hour whose total is unchanged is not rewritten. This ledger has no public endpoint. Its visible effects are the usage.requestsThisMonth total above and the usage Stripe bills (see Usage reporting to Stripe).

Usage reporting to Stripe

Each closed hourly total is sent to Stripe as one Billing Meter event on the meter for that usage (requests, awake time or always-on hours per machine size, or egress per region tier). The event is stamped with the start of the usage hour and identified by the ledger row, so a retried send is not counted twice. Metered subscription items on a Platform subscription are billed from these events at the end of the billing period.

Behavior	Detail
Timing	The platform reports every 15 minutes. An hour is sent after it closes and after the usage collector has recorded it, so usage normally reaches Stripe within about an hour of the hour ending. Usage shown in Stripe can therefore trail real use by that much.
Retries	A usage total is marked as reported only after Stripe accepts the event. If Stripe rejects it or is unreachable, the total stays pending and the next pass sends it again. Nothing is dropped while the hour is inside the age limit below.
Corrections	If an hour’s total changes after it was reported, the platform sends one more event for the difference, which can be negative. If Stripe rejects a correction, it stays pending and is retried; the meter’s sum matches the ledger once it is accepted.
No Stripe customer yet	Usage for a billing account without a Stripe customer stays pending until the account has one, then is sent.
Zero usage	An hour with zero usage is marked reported without sending an event.
Age limit	Stripe accepts usage timestamps only within the past 35 calendar days. The platform sends hours up to 34 days old. Older unreported hours are not sent.
Unmetered usage	Usage with a size or region tier that has no catalog meter is not sent.

Reporting is switched on per deployment and sends usage only where it is enabled. It adds no endpoint and no request or response fields.

Period credit grant

When the invoice for a developer or pro plan is paid, the platform issues the billing account a Stripe credit grant equal to the plan fee. The grant applies to the metered usage items on the subscription (see Usage reporting to Stripe), so the plan fee is spent on usage before any usage charge is billed. It expires at the end of the period the invoice paid for. Unused credit does not roll over.

Behavior	Detail
Amount	The plan fee: $29 for `developer`, $99 for `pro`. If the invoice was discounted (coupon or promotion code), the grant is the amount actually paid, never more.
Expiry	The end of the invoice’s billing period. A grant is not issued for an invoice whose period has already ended.
Plans	`developer` and `pro` only. Invoices with no plan line, for any other plan (including the legacy `enterprise` price), in a currency other than USD, or with nothing paid get no grant.
Proration	A proration line from a mid-period plan change does not issue a grant. The next period’s invoice does.
Order of use	The period grant is applied before card-unlock, promotional and top-up credit, so the credit that expires soonest is spent first.
Duplicates	One grant per invoice. A redelivered or retried payment event does not create a second grant.
Failures	If the grant cannot be issued, for example when Stripe is unreachable or no billing account owns the invoice’s Stripe customer, the event is rejected and Stripe retries it.

The platform also records each grant against your billing account, so your credit balance is computed without calling Stripe. The grant adds no endpoint and no request or response fields.

Spend cap

Stripe totals metered usage only when it invoices, so the platform keeps its own balance from the usage ledger and your credit grants: the credit remaining, minus the usage since the period start that credit did not cover. Seats and tax are not part of it. The balance is recomputed at least hourly. A paid account reaches its spend cap when its plan fee plus the usage that credit did not cover reaches the cap. A Free account reaches its quota at 10,000 requests or 100 awake hours in a UTC calendar month, unless a card-unlock, promotional or top-up credit still has a balance. A subscription that has been past_due for more than 3 days is treated the same as a reached spend cap. Refusing requests at a limit is not active yet; this release computes and stores the limit state. GET /api/v1/billing/spend-cap returns the cap in force and PUT /api/v1/billing/spend-cap changes it. Both use session authentication.

{
  "data": {
    "plan": "developer",
    "planFeeCents": 2900,
    "minSpendCapCents": 2900,
    "defaultSpendCapCents": 5800,
    "spendCapCents": 5800,
    "isDefault": true
  }
}

PUT takes { "spendCapCents": 9000 }, a positive whole number of cents, or { "spendCapCents": null } to return to the default.

Behavior	Detail
Default	2× the plan fee: $58 on `developer`, $198 on `pro`.
Lowest cap	1× the plan fee. A lower value returns `422`. A cap that is not a positive whole number of cents also returns `422`.
`scale`	The cap is set by contract. `PUT` returns `403`.
`free`	Free has hard quotas and no cap. `PUT` returns `403`.
Effect of a change	The stored limit state is recomputed when you change the cap. If that recompute fails, the cap is still saved and the next periodic recompute (at least hourly) applies it.
Plan ends	Cancelling the subscription clears the cap. A later subscription starts at the default.

Top-ups

A top-up buys credit with a one-off card payment. Each top-up creates a Stripe credit grant for the amount paid, tax excluded. The grant has no expiry. It applies to metered usage after the period grant, so the credit that expires soonest is spent first. Top-ups are available in Stripe test mode only for now: with a live Stripe key, POST returns 503 and auto top-up charges nothing. POST /api/v1/billing/top-up takes { "amountCents": 2500 } and returns 201 with a Stripe Checkout URL to send the customer to. The credit is added when Stripe confirms the payment, not when this request returns. The card is saved so that auto top-up can charge it later.

{ "data": { "url": "https://checkout.stripe.com/c/pay/cs_test_..." } }

PUT /api/v1/billing/top-up sets auto top-up and GET /api/v1/billing/top-up returns it. Both use session authentication. PUT takes { "enabled": true, "thresholdCents": 500, "amountCents": 2500 }. When your balance falls below thresholdCents, the platform charges the saved card amountCents and adds that credit. thresholdCents and amountCents may be left out when they were saved earlier. GET returns the same three values and, when the platform turned auto top-up off, disabledReason and disabledAt.

{
  "data": {
    "enabled": false,
    "thresholdCents": 500,
    "amountCents": 2500,
    "disabledReason": "Card charge failed (insufficient_funds): Your card has insufficient funds.",
    "disabledAt": "2026-10-25T12:00:00.000Z"
  }
}

Behavior	Detail
Minimum	2000 cents ($20), for a one-off top-up and for each auto top-up charge. 1999 returns `422`. A non-integer amount, or one above Stripe’s maximum charge (99,999,999 cents), also returns `422`.
Threshold	A whole number of cents, 0 or more. A negative or fractional value returns `422`.
Check frequency	The balance is checked after each recompute of the limit state, which runs at least hourly.
Charge frequency	At most one auto top-up charge per account per UTC hour. A charge is not repeated while its credit has not been added yet.
Declined card	A declined card, or no saved card, turns auto top-up off and records why. The platform does not retry the charge. Saving the settings again clears the recorded reason. Send `"enabled": true` to turn it back on.
Duplicates	One grant per payment. A redelivered or retried payment event does not create a second grant.
Currency	USD only.

Credit and spend-cap alerts

A paid account is told by email, and by a banner on the billing page (/dashboard/billing), when it crosses a threshold. Each threshold fires once per billing period and fires again in the next period.

Alert	Thresholds	What is measured
Credit	50%, 80%, 100%	The part of this period’s usage that credit covered, as a share of that plus the credit still remaining.
Spend cap	80%, 100%	Plan fee plus the usage credit did not cover, as a share of the cap. Counted only once the credit is used up, the same condition under which the cap is reached.

The email names the threshold, your current balance and cap, and links to the billing page, where you can raise the cap or top up. If several thresholds are crossed between two checks, one email for that kind of alert (credit or spend cap) names the highest. Free accounts get no alerts: they have neither credit nor a cap. Alerts are account notices, so unsubscribing from marketing email does not stop them. A failed email send is retried at the next check, which runs at least hourly. The billing page also has forms for the spend cap (the form refuses a cap below your plan fee), one-off top-ups and auto top-up.

POST /v1/billing/subscribe

Initiates a Stripe checkout session to subscribe or upgrade. Use this to go from the free plan to a paid plan. Request body:

{
  "plan": "developer"
}

Response 201:

{
  "data": {
    "url": "https://checkout.stripe.com/pay/cs_..."
  }
}

Redirect the user to url to complete payment. Checkout creates the domain’s Stripe customer on first use and reuses it afterwards. A paid Platform subscription is the plan’s price plus one usage-based item for every Platform meter (requests, awake time and always-on hours per machine size, and egress per region tier). The meter items carry no quantity: usage is reported to them as it happens. Checkout itself contains only the plan. The meter items are added to the subscription when the payment completes, and the plan is recorded on your account only after that succeeds. If adding them fails, the confirmation is retried instead of leaving a paid plan without metering. Subscriptions are created in Stripe’s flexible billing mode, which allows more items per subscription than the default 20 limit. Checkout sells the plan with no extra seats. Extra seats on pro and enterprise are billed at limits.seatPrice per seat.

Cancel subscription

DELETE /v1/billing/subscribe

Cancels the current paid subscription at the end of the current billing period (cancel_at_period_end = true in Stripe). The subscription remains active until the period ends. Response 204: No content.

Change plan

PATCH /v1/billing/plan

Immediately changes the active paid subscription to a different paid plan (e.g. Developer → Pro). This performs an inline Stripe subscription update without a new checkout session. To downgrade to the free plan, use DELETE /v1/billing/subscribe (cancel) instead. To upgrade from the free plan, use POST /v1/billing/subscribe (checkout) instead. Request body:

{
  "plan": "pro"
}

Field	Type	Required	Description
`plan`	string	✓	`developer`, `pro`, or `enterprise`

Response 204: No content. Only the plan’s price changes, and the new price is prorated: the change creates a credit for the unused time on the old plan and a charge for the new one, both billed on the next invoice. The billing cycle does not reset. The subscription’s metered items carry over unchanged. They are billed in arrears on reported usage and are not prorated. If the subscription has extra seats, they follow the plan. Moving between pro and enterprise keeps the seat count and re-prices the seats at the new plan’s rate. Moving to developer, which sells no seats, is refused while extra seats remain:

{
  "error": {
    "code": "conflict",
    "message": "Remove extra seats before changing to the developer plan, which has none."
  }
}

Status	Code	Condition
409	`conflict`	The subscription has extra seats and the target plan sells none. Remove the seats, then retry. The request had no effect.

Billing unavailable errors

POST /v1/billing/subscribe and PATCH /v1/billing/plan price each paid plan (developer, pro, enterprise) from the ezForge Stripe catalog, looking up the plan’s catalog lookup_key when the request is made. Ready and Hub plans are priced from the same catalog. Plan prices don’t need to be configured as price IDs at deploy time. A price ID that is still configured takes precedence over the catalog lookup, so the errors below apply only to plans without one. If the requested plan has no active price in the catalog, both endpoints fail closed instead of creating a checkout session or changing the subscription:

{
  "error": {
    "code": "configuration_error",
    "message": "No active Stripe price for lookup_key: <lookup_key>"
  }
}

Status	Code	Endpoints	Condition
503	`configuration_error`	`POST /v1/billing/subscribe`, `PATCH /v1/billing/plan`	The plan’s price can’t be found in the catalog. The plan is temporarily unpurchasable. Retry later; the request had no effect.
503	`configuration_error`	`POST /v1/billing/subscribe`	Any Platform meter has no active price in the catalog. Checkout fails closed before a customer or session is created, because the subscription could not be given its full meter set. Retry later; the request had no effect.
503	`service_unavailable`	`POST /v1/billing/subscribe`, `PATCH /v1/billing/plan`	Stripe rejected the request as misconfigured. Includes `Retry-After: 60`.

Plan comparison

Feature	Free	Starter	Developer	Pro	Scale
Servers	2	3	10	50	50
Requests / month (not yet metered)	10,000	No hard quota	No hard quota	No hard quota	No hard quota
Regions	`ord` only	All	All	All	All
Log retention (days)	7	7	30	30	90

The Scale server count is set by contract. Until contract terms apply, 50 is the default floor. Accounts on the legacy enterprise plan are reported as scale. See Billing Tiers for full details.

​Get billing status

​Usage reporting to Stripe

​Period credit grant

​Spend cap

​Top-ups

​Credit and spend-cap alerts

​Subscribe / upgrade plan

​Cancel subscription

​Change plan

​Billing unavailable errors

​Plan comparison

Get billing status

Usage reporting to Stripe

Period credit grant

Spend cap

Top-ups

Credit and spend-cap alerts

Subscribe / upgrade plan

Cancel subscription

Change plan

Billing unavailable errors

Plan comparison