Change the billing period of web hosting
POST /api/v2/shared-hosting/{accountId}/actions/billing-cycle
Change how often a web hosting account is billed, for example from monthly to yearly. Read GET /api/v2/shared-hosting/{accountId}/actions/billing-cycle first and send a period from its cycles. Send dryRun: true to see the new price without changing anything. The new period and price apply from the next renewal. An unpaid renewal invoice blocks the change with 409 existing_invoice_blocking. Send cancelExistingInvoice: true to cancel that invoice. A new renewal invoice at the new price is then created and returned in renewalInvoice. When the paid period has already run out, the change is refused with 409 overdue_invoice_blocking until the renewal invoice is paid, also with cancelExistingInvoice. An invoice that cannot be cancelled and replaced automatically, for example one that also bills other services and has credit applied, returns 409 existing_invoice_not_cancellable. Both name the invoice in existingInvoice; pay it first. The account must be active. A contact needs permission to place orders.
Authentication: An API key with the scope write:billing. Also write:services: only when dryRun is not true. Also read:hosting: only when dryRun is true. About keys and scopes
Request
Path parameters
accountIdstringrequiredacct_…).Body
billingCyclestringrequiredcycles from the GET. One of monthly, quarterly, semiannually, annually, biennially, triennially.dryRunbooleancancelExistingInvoicebooleanExample
curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/billing-cycle" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "billingCycle": "annually", "dryRun": true }'curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/billing-cycle" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "billingCycle": "annually" }'curl -X POST "https://cloud.hostup.se/api/v2/shared-hosting/acct_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/billing-cycle" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "billingCycle": "annually", "cancelExistingInvoice": true }'Responses
200 The preview when dryRun is true. Otherwise the result of the change.
{ "changed": true, "currentBillingCycle": "annually", "currencyCode": "SEK"}{ "changed": true, "currentBillingCycle": "annually", "currencyCode": "SEK", "renewalInvoice": { "id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3", "number": "202600002", "amount": 1188, "currencyCode": "SEK", "dueAt": "2026-12-01T00:00:00.000Z", "status": "unpaid", "paymentUrl": "/billing?invoice=202600002" }, "cancelledInvoiceIds": [ "inv_01hxa3b4c5d6e7f8g9h0j1k2m4" ], "cancellationMethod": "invoice"}{ "dryRun": true, "changed": false, "currentBillingCycle": "monthly", "targetBillingCycle": "annually", "targetAmount": 1188, "currencyCode": "SEK", "wouldBlock": false}Response fields
dryRunbooleanchangedbooleancurrentBillingCyclestringmonthly, quarterly, semiannually, annually, biennially, triennially, free.targetBillingCyclestringmonthly, quarterly, semiannually, annually, biennially, triennially, free.targetAmountnumbercurrencyCode.currencyCodestringwouldBlockbooleancancelExistingInvoice: true. Also true when the paid period has ended. cancelExistingInvoice does not help then. With cancelExistingInvoice: true the preview does not look at the invoice’s due date. When only the due date has passed, it says false and the change answers 409 overdue_invoice_blocking. Check that actions.canChangeBillingCycle.code on the GET is not overdue_invoice first.Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | Invalid request. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is shared_hosting_not_found. |
| 409 | The change is blocked. existing_invoice_blocking: an unpaid renewal invoice is open; pay it or resend with cancelExistingInvoice: true. overdue_invoice_blocking: the renewal invoice is unpaid and the paid period has ended or its due date has passed; pay it first. existing_invoice_not_cancellable: the open invoice cannot be cancelled and replaced automatically; pay it first. The invoice is in existingInvoice. With overdue_invoice_blocking and existing_invoice_not_cancellable it can be null; find the unpaid invoice with GET /api/v2/billing/invoices then. recovery.action says which step comes next. scheduled_change_in_progress: a scheduled change already manages this account. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |