---
title: "Turn a bought domain’s auto-renew on or off"
method: PATCH
path: "/api/projects/{id}/domains/{domainId}"
tags: ["domains"]
---

# Turn a bought domain’s auto-renew on or off

`PATCH /api/projects/{id}/domains/{domainId}`

## Request

- Base URL: `https://www.orgo.ai`
- URL: `https://www.orgo.ai/api/projects/{id}/domains/{domainId}`
- Auth: HTTP bearer

Body: { "auto_renew": true | false }. Auto-renew is on when a domain is bought (off when it is adopted from another environment). Orgo renews the domain in its last 14 days, from the payer’s Orgo credits, and emails the payer 30 days before with the day the price is taken and the price. Turning it on (even when it is on) makes you the payer from the next renewal on, and clears a no_payer or insufficient_credits renewal_error so the next daily run tries again; a renewal already held stays with its payer. Turning it off gives back any credits held for a renewal not yet sent; one already sent to the registry finishes, and the answer says renewal_state "renewing". Off, the domain expires at expires_at and may become available to others. Write access, with a session or an account-wide key: a workspace-scoped key gets 403 ACCOUNT_KEY_REQUIRED, since turning it on spends your credits.

## Path parameters

- `id` string, uuid, required
- `domainId` string, uuid, required

## Request body

- object
  - `auto_renew` boolean, required

## Response `200`

{ domain }

- object
  - `domain` RegisteredDomain, required
    - `id` string, uuid, required
    - `domain` string, required
    - `status` 'pending' | 'active', required: pending: the registry has not confirmed it yet; its price is held from the credits until it does.
    - `expires_at` string, date-time, nullable, required: When the term ends, as the registry has it. With auto_renew on it renews before then.
    - `created_at` string, date-time, required
    - `auto_renew` boolean, required: Orgo renews it in its last 14 days from the payer’s Orgo credits. On when bought, off when adopted.
    - `renewal_cents` integer, nullable, required: What the next renewal costs, for renewal_years years. null while there is no price.
    - `renewal_years` integer, required: The years one renewal adds: 1 for most extensions, 2 for a few (like .ai).
    - `renewal_paid_by` 'you' | 'member' | 'null', nullable, required: Whose Orgo credits pay the renewal: yours, or another member’s (whoever turned auto-renew on last, else the buyer). null with auto-renew off.
    - `renewal_state` 'off' | 'scheduled' | 'renewing' | 'retrying' | 'expired', required: off: auto-renew is off and it expires at expires_at. scheduled: the price is taken 14 days before expires_at, and it renews then (only where renewals_enabled). renewing: the renewal is with the registry (it can take up to a day to confirm). retrying: the last try failed (renewal_error) and Orgo tries again every day until expiry. expired: expires_at has passed.
    - `renewal_error` 'insufficient_credits' | 'no_payer' | 'registry_refused' | 'null', nullable, required: Why the last try failed, while retrying: the payer’s credits fall short, the payer can no longer pay (turn auto-renew on, PATCH true, to pay yourself), or the registry refused it.
    - `pointed` object[], required: Names on the domain connected to a computer.
      - `domain` string
      - `computer_id` string, uuid
      - `computer_name` string, nullable
      - `status` string: The custom domain’s status (pending, verifying, active, ...).

## Other responses

- `400`: auto_renew is not true or false (INVALID_AUTO_RENEW).
- `401`: Unauthenticated.
- `403`: A workspace-scoped key (ACCOUNT_KEY_REQUIRED), view-only access (workspace_read_only), no access, or a share-link guest.
- `404`: Domains are not enabled for this account (DOMAINS_NOT_ENABLED), or the workspace has no such active domain (DOMAIN_NOT_FOUND).
- `409`: The domain is still being registered (DOMAIN_PENDING).
- `429`: Over one of the account's rate limits (rate_limited): `limit` names it, `retry_after` and Retry-After say how many seconds to wait. Limits are per account (the workspace owner when the request acts on a computer or a workspace) and set by its plan (x-rate-limits).
- `503`: Domains are unavailable right now (DOMAINS_UNAVAILABLE).

## Changes

- **2026-11-01** `60e768a2bb9d`: 12 info
  - added the optional property `docs_url` to the response with the `400` status
  - added the optional property `docs_url` to the response with the `403` status
  - added the optional property `docs_url` to the response with the `404` status
  - added the optional property `docs_url` to the response with the `409` status
  - …8 more
- **2026-10-30** `afb6f0ee1aac`: 1 info
  - added the non-success response with the status `429`
- **2026-10-26** `3cc83acab9fd`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/orgo/apis/orgo-api/changes/api/projects/:id/domains/:domainId/patch.md)

---

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