Skip to content

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

accountIdstringrequired
The web hosting account ID (acct_…).

Body

billingCyclestringrequired
The new billing period. It must be one of the account’s cycles from the GET. One of monthly, quarterly, semiannually, annually, biennially, triennially.
dryRunboolean
Return the new price without changing anything. Default false.
cancelExistingInvoiceboolean
Cancel an unpaid renewal invoice that blocks the change and create a new one at the new price. Default false.

Example

POST /api/v2/shared-hosting/{accountId}/actions/billing-cycle
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
}'

Responses

200 The preview when dryRun is true. Otherwise the result of the change.

{
"changed": true,
"currentBillingCycle": "annually",
"currencyCode": "SEK"
}
Response fields
dryRunboolean
Always true on a preview.
changedboolean
Always false on a preview.
currentBillingCyclestring
The account’s billing period now. One of monthly, quarterly, semiannually, annually, biennially, triennially, free.
targetBillingCyclestring
The period you asked for. One of monthly, quarterly, semiannually, annually, biennially, triennially, free.
targetAmountnumber
The price per period after the change, in currencyCode.
currencyCodestring
The account’s currency.
wouldBlockboolean
True when an unpaid invoice would block the change unless you send cancelExistingInvoice: 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.

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is shared_hosting_not_found.
409The 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.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.