# renew_domain

Source: https://modulify.ai/docs/api/bought-domains/renew-domain

Starts renewing a bought domain for more years and returns a Stripe checkout link for a person to pay on.

- Title: Renew a domain through a checkout link
- Scope: `domains:buy`
- Access: Makes changes
- Endpoint: `POST /v1/renew_domain`

Like `buy_domain`, it never charges a card. The answer carries `checkoutUrl` and `orderId`, the tool tells the client to give you the link and never open it itself, and the domain is renewed only once someone pays on it. The years are then added to `Expires_At`, and the workspace owner and members are emailed. If the registrar refuses the renewal after payment, the payment is refunded.

A domain with `AutoRenew` true is renewed by Modulify before it expires, see `set_domain_auto_renew`, and can still be renewed with this tool, for more years or after an automatic attempt failed. One with `AutoRenew` false is renewed only after its renewal is paid, and otherwise it expires at `Expires_At`, because Name.com's own auto renew always stays off. A domain in the `active`, `expiring` or `expired` state can be renewed, and one already registered close to 10 years ahead cannot. An expired one can still be renewed at the normal renewal price until its `RenewBy`, the last day of the grace period Name.com sets for its extension. After that day Name.com removes it from the account and it shows as `released`, see [After a domain expires](https://modulify.ai/docs/publish/buy-a-domain#after-a-domain-expires).

Agree the term and the price first: read them with `get_domain_price`, passing `domainId` and `years`, and pass its `AmountCents` as `amountCents`. When the price has moved since, nothing opens and the call is refused with the new `AmountCents`. The link works for 60 minutes, a new `renew_domain` call for the same domain closes any earlier link, and `cancel_domain_checkout` closes it with the `orderId`. After paying, the person lands on the domain's page. Like a `buy_domain` link, it does not save the card to the owner's account.

Only the workspace owner can renew domains, and a workspace can start 10 purchases and renewals an hour. See [Renew a domain](https://modulify.ai/docs/publish/buy-a-domain#renew-a-domain).

## Request

Call it with a `POST` to `https://api.modulify.ai/v1/renew_domain`, sending the inputs below as a JSON object. The token needs the `domains:buy` scope.

It makes changes, so send an [Idempotency-Key](https://modulify.ai/docs/api/idempotency) header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

```bash
curl -X POST https://api.modulify.ai/v1/renew_domain \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"WORKSPACE_ID","domainId":"DOMAIN_ID","years":1,"amountCents":1}'
```

Over MCP, the same method is the [renew_domain tool](https://modulify.ai/docs/mcp/bought-domains/renew-domain).

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string | Yes | The workspace that owns the domain. |
| `domainId` | string | Yes | The `_id` of the bought domain, from `list_bought_domains`. |
| `years` | integer | Yes | How many years to add, the same term `get_domain_price` was asked for. |
| `amountCents` | integer | Yes | `AmountCents` from `get_domain_price` for this domain and term. |

## Response

Every call answers with the [JSON envelope](https://modulify.ai/docs/api/requests-and-responses#the-response) of `success`, `message`, `data`, `code` and `version`. `data` holds the result described above, and on a method that returns a total, `count` carries it. The [response headers](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) carry the call's `X-Request-Id` and what is left of your per-minute budget in `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`. [Errors](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.