Skip to content

List renewal periods for a domain

GET /api/v2/domains/{id}/billing-cycle

List the renewal periods you can choose for a domain, with the renewal price of each. To change the period, choose one row from options[] and send it to POST /api/v2/domains/{id}/billing-cycle. Periods vary by domain ending. You must not assume every 1-9 year value is offered. Rows for 1, 2 and 3 years have a billingCycle (annually, biennially, triennially). Longer rows have billingCycle: null. Send their periodYears instead. When the domain has an unpaid renewal or another open order, locked is true and options is empty. The order is in pendingRenewalOrder or pendingOrder. Pay or cancel it first. To decline a renewal, use POST /api/v2/domains/{id}/actions/respond-to-renewal. The period of a premium domain cannot be changed.

Authentication: An API key with the scope read:domains. About keys and scopes

Request

Path parameters

idstringrequired
The domain ID (dom_…).

Example

GET /api/v2/domains/{id}/billing-cycle
curl "https://cloud.hostup.se/api/v2/domains/dom_01hxa3b4c5d6e7f8g9h0j1k2m3/billing-cycle" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The renewal periods and whether you can change the period now.

Response 200
{
"currentBillingCycle": "annually",
"currentPeriodYears": 1,
"currencyCode": "SEK",
"options": [
{
"billingCycle": "annually",
"periodYears": 1,
"years": 1,
"amount": 169,
"currencyCode": "SEK",
"renewPrice": 169,
"isCurrent": true
},
{
"billingCycle": "biennially",
"periodYears": 2,
"years": 2,
"amount": 338,
"currencyCode": "SEK",
"renewPrice": 338,
"isCurrent": false
},
{
"billingCycle": "triennially",
"periodYears": 3,
"years": 3,
"amount": 507,
"currencyCode": "SEK",
"renewPrice": 507,
"isCurrent": false
},
{
"billingCycle": null,
"periodYears": 5,
"years": 5,
"amount": 845,
"currencyCode": "SEK",
"renewPrice": 845,
"isCurrent": false
}
],
"locked": false,
"lockReason": null,
"pendingRenewalOrder": null,
"pendingOrder": null,
"actions": {
"canChangeBillingCycle": {
"allowed": true,
"reason": null
}
}
}
Response fields
currentBillingCyclestring or null
The current period as annually, biennially or triennially. Null for longer periods. One of annually, biennially, triennially.
currentPeriodYearsinteger or null
The current renewal period, in years. 1 to 9.
currencyCodestring
ISO 4217 currency of every amount in options[].
optionsarray of object
The renewal periods this domain offers. They vary by TLD. Send one of these rows to POST /api/v2/domains/{id}/billing-cycle.
billingCyclestring or null
annually, biennially or triennially for 1, 2 and 3 years. Null for 4 to 9 years. Send periodYears for those. One of annually, biennially, triennially.
periodYearsinteger
1 to 9.
yearsinteger
The same as periodYears. 1 to 9.
amountnumber or null
The renewal price for this period, in currencyCode.
currencyCodestring
ISO 4217 currency of amount and renewPrice.
renewPricenumber or null
Deprecated. The same as amount.
isCurrentboolean
lockedboolean
lockReasonstring or null
pendingRenewalOrdernull
pendingOrdernull
actionsobject
canChangeBillingCycleobject
allowedboolean
reasonstring or null
codestring or null
One of pending_renewal_order, pending_domain_order, locked.

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 domain_not_found.
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.