CrabGlamp

Switch billing type

Move an Agent between pay-as-you-go metered billing and subscribe-and-save flat-rate billing without recreating the Agent. The switch takes effect immediately; usage already accrued rolls forward onto your invoice. This how-to covers the dashboard flow, the API call, and the cost implications you should expect.

Last updated:

You have an Agent on one billing type and want to switch. The Agent does not need to be stopped first.

When to switch

  • Metered → subscribed — cheaper if you keep the Agent running most of the month.
  • Subscribed → metered — cheaper if your usage is intermittent.

Account and billing covers the per-size, per-region break-even math.

From the dashboard

  1. Open the Agent's settings page: /dashboard/agents/{id}/settings.
  2. Find the Billing section.
  3. Click Switch billing type.
  4. Confirm in the dialog.

The dashboard makes one API call and the Agent's billing type changes immediately. Usage already accrued on the old type is reported on your invoice; new usage accrues on the new type from the moment you switch.

The underlying endpoint

The dashboard issues PATCH /api/agents/[id]/billing with:

{ "billingType": "subscription" }

It uses your Clerk session — there is no on-VM HMAC path for billing changes, so switch from the dashboard. It returns 200 with { success, billingType, addedNewSlot }. On failure, the response is a structured validation-error envelope (see the reference).

What you should expect

  • Existing accrued usage on the previous billing type stays accrued and is billed on your invoice for the period.
  • The dashboard shows the new billing type within a refresh; your invoice for the current period reflects both rates.
  • Switching to subscribe-and-save takes a slot — it reuses a free one in the matching size and region if you have it, otherwise it adds one (addedNewSlot: true). Switching to pay-as-you-go frees the slot the Agent held but keeps it on your subscription; remove it from /dashboard/billing to stop paying for it. See Account & billing.

Related

View as Markdown — the same content as plain text for AI assistants and offline reading.

Was this helpful?