Skip to content

Switch monthly or hourly

Change a capacity purchase's billing model. Switching to monthly takes effect once the first payment completes. Switching to hourly takes effect at the end of the paid period.

Parameters

#
capacitystringRequired
Capacity purchase ID from capacity view.
monthlyboolean
Switch to monthly billing after payment for the first month completes.
hourlyboolean
Switch to hourly billing at the end of the current paid period.
dry_runboolean
Preview the change without applying it.
organizationstring
Organization name or ID. A credential, named resource or sole membership can select the organization for you.

Returns

#
dataobjectAlways present
A purchase change and its completion, schedule or payment status.
Show 12 attributesHide attributes
activeboolean
Whether the resulting purchase is active after the payment step. May be omitted.
atstring (date-time)
When a scheduled change takes effect. May be omitted.
changestringAlways present
Requested purchase change.
charged_centsinteger
Amount charged now, or previewed in a dry run, in cents. May be omitted.
checkout_urlstring
Payment page when checkout is needed. May be omitted.
doneboolean
Whether the change has already completed. May be omitted.
dry_runboolean
True when nothing was changed. May be omitted.
idstringAlways present
Purchase being changed.
invoice_urlstring
Invoice page when further payment action is needed. May be omitted.
messagestring
Result or required next action. May be omitted.
refunded_centsinteger
Amount refunded, in cents. May be omitted.
unknownboolean
Whether the payment outcome is uncertain. Read the purchase before retrying. May be omitted.

Errors

#
CodeStatusWhat happened
invalid400An input is missing or invalid.
unauthenticated401The credential is missing, invalid, expired or revoked.
denied403The caller lacks permission for this action.
not_found404The resource is absent or inaccessible to this caller.
conflict409The request conflicts with the current resource state or an earlier request.
over_capacity409The request exceeds a resource or credential allowance.
access_list_full409The change would exceed the access-list allowance.
payment_required402Payment or credit is required.
rate_limited429The caller's request rate exceeds its limit.
busy429Too much work is in progress to accept this request.
unknown503The outcome is unconfirmed; a change may have happened.
unavailable503The service or requested feature is unavailable.

Notes

#
  • CLI: heaven login with HEAVEN_API_KEY unset. MCP: Heaven sign-in. cURL: HEAVEN_SIGN_IN_KEY from approved device sign-in (POST /v1/auth/create).
  • A key limited to a command list cannot run this command.
  • Monthly: Switch to monthly billing after the first month is paid. Required: monthly. Optional: dry_run, organization.
  • Hourly: Switch to hourly billing when the paid monthly period ends. Required: hourly. Optional: dry_run, organization.