---
title: "Renew or register a held domain"
method: POST
path: "/v1/domains/{domainId}/registration"
tags: ["Domains"]
---

# Renew or register a held domain

`POST /v1/domains/{domainId}/registration`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/domains/{domainId}/registration`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.spacefast.com/v1/auth/oauth2/authorize`, token URL `https://api.spacefast.com/v1/auth/oauth2/token`; client credentials, token URL `https://api.spacefast.com/v1/auth/oauth2/token`, scopes: `domains:write`)

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

## Path parameters

- `domainId` string, required

## Request body

- union
  - object
    - `action` 'purchase', required
    - `period` integer: Registration period in years.
    - `contactId` string: Registrant contact record to use.
  - object
    - `action` 'renew', required
    - `period` 1: Years. Only 1 is offered today.
  - object
    - `action` 'transfer_in', required
    - `authCode` string, required: Transfer authorization code from the current registrar.
    - `contactId` string: Registrant contact record to use.
  - object
    - `action` 'transfer_out', required

## Response `200`

Response for status 200

- object
  - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
  - `data` object, required
    - `registration` object, required
      - `id` string, nullable, required: Registration or transfer record id; null when unregistered.
      - `domainId` string, required: Domain inventory record (`dom_...`).
      - `hostname` string, required: Registered hostname.
      - `provider` 'dsapi' | 'manual', nullable, required: Wrapped registrar bridge where the registration lives.
      - `status` string, required: Registration lifecycle status. `pending_payment` means checkout is open and nothing is registered yet.
      - `expiresAt` string, date-time, nullable, required: Instant when the registration expires.
      - `redemptionEndsAt` string, date-time, nullable, required: Instant when the redemption window ends after expiry.
      - `autoRenew` boolean, required: Saved auto-renew preference. Nothing renews on its own yet; renew by hand.
      - `transferLock` boolean, required: Whether outbound transfers are locked.
      - `privacySetting` 'enable_privacy_service' | 'redact_contact_info' | 'disclose_contact_info', nullable, required: WHOIS privacy behavior.
      - `contactId` string, nullable, required: Registrant contact record.
      - `failureReason` string, nullable, required: Provider failure detail when status is `failed`.
      - `purchase` object, nullable, required: Money state of the current purchase or renewal line; null when none is in flight.
        - `intentId` string, required: Purchase intent that paid for this line.
        - `lineStatus` 'awaiting_payment' | 'submitting' | 'settled' | 'refunding' | 'refunded' | 'cancelled', required
        - `checkout` object, nullable: Existing open payment link, requested with includeCheckout and returned only to callers authorized to purchase this domain. Null when no open link is available; check checkoutUnavailable for lookup failures. Omitted when not requested or not authorized.
          - `id` string, required: Existing Stripe Checkout session id.
          - `url` string, uri, required: Open this existing checkout to complete payment.
          - `expiresAt` string, date-time, required: When this checkout expires.
        - `checkoutUnavailable` boolean: 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.
        - `quotedFeeAmountCents` integer, nullable, required: Registrar fee before tax, in cents.
        - `paidAmountCents` integer, nullable, required: What the customer paid for this line, tax included, in cents.
        - `refund` object, nullable, required
          - `reference` string, required: Stripe refund id.
          - `amountCents` integer, required
          - `refundedAt` string, date-time, required
      - `createdAt` string, date-time, nullable, required
      - `updatedAt` string, date-time, nullable, required
    - `checkout` object, nullable, required: Payment step for renew and purchase; null when nothing is due.
      - `id` string, required: Stripe Checkout session id.
      - `url` string, uri, required: Open this to pay. Nothing is charged until payment completes here.
      - `expiresAt` string, date-time, required
      - `subtotalCents` integer, required
      - `currency` 'USD', required
      - `lines` object[], required
        - `domainId` string, required
        - `registrationId` string, required
        - `name` string, required
        - `amountCents` integer, required: Price before tax, in cents: the registrar fee plus any ICANN fee.
  - `operation` object, nullable, required: Background operation handle when asynchronous work remains after this mutation; null when it completed synchronously.
    - `id` string, required
    - `kind` string, required
    - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
    - `resources` object[], required
      - `type` string, required
      - `id` string, required
    - `progress` object
      - `total` integer, required
      - `completed` integer, required
      - `failed` integer, required
    - `diagnostics` object[]
      - `code` string, required: Stable snake_case diagnostic code naming the public contract that produced it.
      - `severity` 'info' | 'warning' | 'error', required: How actionable the diagnostic is.
      - `message` string, required: Human-readable explanation with enough detail to act on.
      - `path` string, nullable: Artifact path the diagnostic points at, for example "_headers:12", when one exists.
      - `provider` 'infra' | 'dns' | 'registrar' | 'runtime', nullable: Upstream system the diagnostic originated from, when not Spacefast itself.
      - `details` object, nullable: Machine-readable context for the diagnostic code.
      - `fix` string, nullable: Concrete, agent-actionable remediation hint, when one can be derived.
      - `retryable` boolean, nullable: Whether retrying the same operation can resolve this diagnostic without the caller changing anything.
    - `createdAt` string, date-time, required
    - `finishedAt` string, date-time

## Other responses

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

---

[API](https://skmtc.dev/spacefast/apis/spacefast-api.md) · [All operations](https://skmtc.dev/spacefast/apis/spacefast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spacefast/apis/spacefast-api/revisions/bd165bc7c983?raw)