Skip to content
Docs
Esc
↑↓navigate↵open⌘Jpreview

Renew or register a held domain

renew (and purchase, a one-name purchaseDomain) returns data.checkout.url for a person to open; nothing is charged until they pay there, and the registrar is asked only after payment. Poll getDomainRegistration for the outcome. Transfers aren’t available yet: transfer_in and transfer_out refuse with domain_transfer_unavailable and change nothing.

POST/v1/domains/{domainId}/registration
Authorization
AuthorizationBearer token · headerrequired

Better Auth session, OAuth access token, OAuth client-credentials token, or sfm_ Space machine credential.

or
AuthorizationOAuth2 access token · headerrequired

OAuth 2.0 with explicit Spacefast capability scopes. Use the authorization-code flow for people and client credentials for machines.

Scopes:domains:write
Path parameters
domainIdstringrequired
Request body
requiredapplication/json
One of:
object
actionstringrequired
analyticsobject
Show properties
sessionIdstring<uuid>required
matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
traceIdstring<uuid>required
matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
anonymousIdstringrequired
min length 1 · max length 128 · matches ^[A-Za-z0-9_-]+$
pathstringrequired
min length 1 · max length 2048 · matches ^\/(?:[^/?#]+\/){0,2}domains(?:\/[^?#]*)?$
periodinteger

Registration period in years.

min 1 · max 10
contactIdstring

Registrant contact record to use.

min length 1
object
actionstringrequired
analyticsobject
Show properties
sessionIdstring<uuid>required
matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
traceIdstring<uuid>required
matches ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
anonymousIdstringrequired
min length 1 · max length 128 · matches ^[A-Za-z0-9_-]+$
pathstringrequired
min length 1 · max length 2048 · matches ^\/(?:[^/?#]+\/){0,2}domains(?:\/[^?#]*)?$
periodnumber

Years. Only 1 is offered today.

object
actionstringrequired
authCodestringrequired

Transfer authorization code from the current registrar.

min length 1 · max length 255
contactIdstring

Registrant contact record to use.

min length 1
object
actionstringrequired
Responses
200

Response for status 200

$schemastring<uri>

Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.

dataobjectrequired
Show properties
registrationobjectrequired
Show properties
idstring | nullrequired

Registration or transfer record id; null when unregistered.

domainIdstringrequired

Domain inventory record (dom_...).

hostnamestringrequired

Registered hostname.

providerstring | nullrequired

Wrapped registrar bridge where the registration lives.

Show properties
Any of:
string
string
null
null
statusstringrequired

Registration lifecycle status. pending_payment means checkout is open and nothing is registered yet.

expiresAtstring<date-time> | nullrequired

Instant when the registration expires.

Show properties
Any of:
string<date-time>
string<date-time>
null
null
redemptionEndsAtstring<date-time> | nullrequired

Instant when the redemption window ends after expiry.

Show properties
Any of:
string<date-time>
string<date-time>
null
null
autoRenewbooleanrequired

Saved auto-renew preference. Nothing renews on its own yet; renew by hand.

transferLockbooleanrequired

Whether outbound transfers are locked.

privacySettingstring | nullrequired

WHOIS privacy behavior.

Show properties
Any of:
string
string
null
null
contactIdstring | nullrequired

Registrant contact record.

failureReasonstring | nullrequired

Provider failure detail when status is failed.

purchaseobject | nullrequired

Money state of the current purchase or renewal line; null when none is in flight.

Show properties
Any of:
object
intentIdstringrequired

Purchase intent that paid for this line.

lineStatusstringrequired
Allowed:awaiting_paymentsubmittingsettledrefundingrefundedcancelled
checkoutobject | null

The open payment link, when you request includeCheckout. You get it only when you may purchase this domain and, when the checkout was opened with billing authority over the paying team, hold that authority too. Null when you cannot get an open link; check checkoutUnavailable for lookup failures. Omitted when you do not request it or may not purchase this domain.

Show properties
Any of:
object
idstringrequired

Existing Stripe Checkout session id.

urlstring<uri>required

Open this existing checkout to complete payment.

expiresAtstring<date-time>required

When this checkout expires.

matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
null
null
checkoutUnavailableboolean

True when the requested payment link could not be retrieved or verified. Registration status remains available. Retry the read to recover the existing checkout; do not start another purchase.

quotedFeeAmountCentsinteger | nullrequired

Registrar fee before tax, in cents.

Show properties
Any of:
integer
integer
null
null
paidAmountCentsinteger | nullrequired

What the customer paid for this line, tax included, in cents.

Show properties
Any of:
integer
integer
null
null
refundobject | nullrequired
Show properties
Any of:
object
referencestringrequired

Stripe refund id.

amountCentsintegerrequired
min -9007199254740991 · max 9007199254740991
refundedAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
null
null
null
null
createdAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
updatedAtstring<date-time> | nullrequired
Show properties
Any of:
string<date-time>
string<date-time>
null
null
checkoutobject | nullrequired

Payment step for renew and purchase; null when nothing is due.

Show properties
Any of:
object
idstringrequired

Stripe Checkout session id.

urlstring<uri>required

Open this to pay. Nothing is charged until payment completes here.

expiresAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
subtotalCentsintegerrequired
min -9007199254740991 · max 9007199254740991
currencystringrequired
linesobject[]required
Show properties
Array of object
domainIdstringrequired
registrationIdstringrequired
namestringrequired
amountCentsintegerrequired

Price before tax, in cents: the registrar fee plus any ICANN fee.

min -9007199254740991 · max 9007199254740991
null
null
operationobject | nullrequired

Background operation handle when asynchronous work remains after this mutation; null when it completed synchronously.

Show properties
Any of:
object
idstringrequired
kindstringrequired
statusstringrequired
Allowed:queuedrunningsucceededfailedcanceled
resourcesobject[]required
Show properties
Array of object
typestringrequired
idstringrequired
progressobject
Show properties
totalintegerrequired
min 0 · max 9007199254740991
completedintegerrequired
min 0 · max 9007199254740991
failedintegerrequired
min 0 · max 9007199254740991
diagnosticsobject[]
Show properties
Array of object
codestringrequired

Stable snake_case diagnostic code naming the public contract that produced it.

severitystringrequired

How actionable the diagnostic is.

Allowed:infowarningerror
messagestringrequired

Human-readable explanation with enough detail to act on.

pathstring | null

Artifact path the diagnostic points at, for example "_headers:12", when one exists.

providerstring | null

Upstream system the diagnostic originated from, when not Spacefast itself.

Show properties
Any of:
string
string
null
null
detailsobject | null

Machine-readable context for the diagnostic code.

Show properties
Any of:
object
object
null
null
fixstring | null

Concrete, agent-actionable remediation hint, when one can be derived.

retryableboolean | null

Whether retrying the same operation can resolve this diagnostic without the caller changing anything.

createdAtstring<date-time>required
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
finishedAtstring<date-time>
matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
null
null
default

Problem details (RFC 9457). Any 4xx/5xx response is one application/problem+json document.

$schemastring<uri>

Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.

typestringrequired

Problem type URI resolving to the error docs page. The server derives it mechanically from code against the docs origin.

titlestringrequired

Short human-readable summary of the problem type. The server derives it mechanically from code.

statusintegerrequired

HTTP status code of this response, repeated in the body.

min -9007199254740991 · max 9007199254740991
detailstringrequired

Human-readable failure explanation for this occurrence.

codestringrequired

Stable snake_case error code naming the failed public contract.

pointerstring

RFC 6901 JSON Pointer into the failing request field, for example "/files/37/path", on validation failures.

detailsobject

Machine-readable context for the error code.

fixstring

One sentence on what to do about this error code, the same text as the type page. Read it before retrying.

suggestionsstring[]

Actionable recovery steps safe to show in dashboards, SDKs, and CLI output.

nextstring[]

Copy-pasteable commands or API requests an agent can run next.

requestIdstringrequired

The request id to quote when contacting support.

Try it
Server
Authorization
Parameters
Bodyapplication/json
Request
curl -X POST 'https://api.spacefast.com/v1/domains/string/registration' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "action": "purchase",
  "analytics": {
    "sessionId": "f6567dd8-e069-418e-8893-7d22fcf12459",
    "traceId": "729bb1bf-882d-483b-89d3-5855dc5af3aa",
    "anonymousId": "string",
    "path": "string"
  },
  "period": 1,
  "contactId": "string"
}'
Response
{
  "$schema": "http://example.com",
  "data": {
    "registration": {
      "id": "string",
      "domainId": "string",
      "hostname": "string",
      "provider": "dsapi",
      "status": "string",
      "expiresAt": "2019-08-24T14:15:22Z",
      "redemptionEndsAt": "2019-08-24T14:15:22Z",
      "autoRenew": true,
      "transferLock": true,
      "privacySetting": "enable_privacy_service",
      "contactId": "string",
      "failureReason": "string",
      "purchase": {
        "intentId": "string",
        "lineStatus": "awaiting_payment",
        "checkout": {
          "id": "string",
          "url": "http://example.com",
          "expiresAt": "2019-08-24T14:15:22Z"
        },
        "checkoutUnavailable": true,
        "quotedFeeAmountCents": -9007199254740991,
        "paidAmountCents": -9007199254740991,
        "refund": {
          "reference": "string",
          "amountCents": -9007199254740991,
          "refundedAt": "2019-08-24T14:15:22Z"
        }
      },
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    },
    "checkout": {
      "id": "string",
      "url": "http://example.com",
      "expiresAt": "2019-08-24T14:15:22Z",
      "subtotalCents": -9007199254740991,
      "currency": "USD",
      "lines": [
        {
          "domainId": "string",
          "registrationId": "string",
          "name": "string",
          "amountCents": -9007199254740991
        }
      ]
    }
  },
  "operation": {
    "id": "string",
    "kind": "string",
    "status": "queued",
    "resources": [
      {
        "type": "string",
        "id": "string"
      }
    ],
    "progress": {
      "total": 0,
      "completed": 0,
      "failed": 0
    },
    "diagnostics": [
      {
        "code": "string",
        "severity": "info",
        "message": "string",
        "path": "string",
        "provider": "infra",
        "details": {
          "property1": null,
          "property2": null
        },
        "fix": "string",
        "retryable": true
      }
    ],
    "createdAt": "2019-08-24T14:15:22Z",
    "finishedAt": "2019-08-24T14:15:22Z"
  }
}

Was this page helpful?