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
#| Code | Status | What happened |
|---|---|---|
| invalid | 400 | An input is missing or invalid. |
| unauthenticated | 401 | The credential is missing, invalid, expired or revoked. |
| denied | 403 | The caller lacks permission for this action. |
| not_found | 404 | The resource is absent or inaccessible to this caller. |
| conflict | 409 | The request conflicts with the current resource state or an earlier request. |
| over_capacity | 409 | The request exceeds a resource or credential allowance. |
| access_list_full | 409 | The change would exceed the access-list allowance. |
| payment_required | 402 | Payment or credit is required. |
| rate_limited | 429 | The caller's request rate exceeds its limit. |
| busy | 429 | Too much work is in progress to accept this request. |
| unknown | 503 | The outcome is unconfirmed; a change may have happened. |
| unavailable | 503 | The service or requested feature is unavailable. |
Notes
#- CLI:
heaven loginwithHEAVEN_API_KEYunset. MCP: Heaven sign-in. cURL:HEAVEN_SIGN_IN_KEYfrom 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.