# buy_domain

Source: https://modulify.ai/docs/mcp/bought-domains/buy-domain

Starts buying a domain for a workspace and returns a Stripe checkout link for a person to pay on.

- Title: Buy a domain through a checkout link
- Scope: `domains:buy`
- Access: Makes changes

It never charges a card, not even the one saved on the owner's account. The answer carries `checkoutUrl`, a Stripe checkout link, and the `orderId` of the order, and the domain is registered only once someone opens the link and pays. The tool tells the client to give you the link and never open it itself. Once it is paid, the domain shows in `list_bought_domains` as `pending` for a few moments and then `active`, and the workspace owner and members are emailed. If the registrar refuses it after payment, the payment is refunded and the domain shows as `failed`.

Agree the domain, the term and the price first: read the price with `get_domain_price` for the same domain 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`.

`contact` takes the fields of [Add the registrant](https://modulify.ai/docs/publish/buy-a-domain#add-the-registrant). `Phone` has to be a possible number for its country code, such as `+14155550100`, and is saved in E.164 form. A number without `+` is read as a number of the contact's `Country`, and one that is not a possible number is refused with `Phone must be a real number with its country code, like +14155550100!` `Country` is a two-letter code, `XK` for Kosovo, and `KV` is read as `XK`. `get_domain_price` returns the details you entered on your last domain order in this workspace. When it answers `PrivacyAvailable` true, WHOIS privacy keeps them out of the public record for free. Otherwise the extension offers no WHOIS privacy and the registry may publish them, which the tool tells the client to mention before you agree. When the details are new to Name.com, it emails the registrant to confirm them, and the domain can be suspended if they do not confirm within 15 days.

The link works for 60 minutes, and a new `buy_domain` call for the same domain closes any earlier link. `cancel_domain_checkout` closes it with the `orderId`. Paying on it brings the person back to the workspace's **Domains** page. Unlike a checkout page opened on the **Domains** page, a link opened this way does not save the card to the owner's account.

`autoRenew` true turns auto-renew on for the new domain, so Modulify later renews it itself on the saved card of whoever the token belongs to, see `set_domain_auto_renew`. It is off when left out, because paying on the link saves no card, unlike a domain bought in the **Register domain** dialog, which always starts with it on. The tool tells the client to pass true only when you already have a saved card and agreed to those later charges, or to turn auto-renew on afterwards with `set_domain_auto_renew`.

`connectProjectId` names a site of the same workspace to connect the domain to. Modulify then connects it as soon as its registration is confirmed, the way `add_custom_domain` would, even when the registrar confirms it later, so nobody has to add it afterwards. It is ignored when it is not a site of that workspace. The connection is made as whoever the token belongs to, so they must be allowed to manage that site's domains and the site needs room for another custom domain. When the connection is refused, the domain is still registered and can be added with `add_custom_domain` once it is `active`.

`connectHostname` connects a subdomain of the domain to that site instead of the domain itself, such as `blog.acme.com` when buying `acme.com`. It is ignored without `connectProjectId` or when it is not under the domain.

The purchase is refused when the domain is taken, when its extension's registry needs extra details Modulify cannot collect yet, when the name has characters other than a to z, 0 to 9 and hyphens, when the workspace already owns it and while a payment for it is being processed, see [When it does not go through](https://modulify.ai/docs/publish/buy-a-domain#when-it-does-not-go-through). Only the workspace owner can buy domains, and a workspace can start 10 purchases and renewals an hour.

## Inputs

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `workspaceId` | string | Yes | The workspace that will own the domain. |
| `domain` | string | Yes | The domain to buy, such as `acme.com`. Up to 253 characters. |
| `years` | integer | Yes | The term in whole years, the same one `get_domain_price` was asked for. |
| `amountCents` | integer | Yes | `AmountCents` from `get_domain_price` for this domain and term. |
| `contact` | object | Yes | The registrant, the person or company who will legally own the domain. `FirstName`, `LastName`, `Email`, `Phone`, a real number with its country code such as `+14155550100`, `Address1`, `City`, `State`, `Zip` and `Country`, a two-letter code such as `US`, or `XK` for Kosovo, are required, and `CompanyName` and `Address2` are optional. Each field takes up to 255 characters. |
| `autoRenew` | boolean | No | True turns auto-renew on for the domain once it is registered, charging the saved card of whoever the token belongs to for each renewal. Defaults to false. |
| `connectProjectId` | string | No | The id of a site of this workspace to connect the domain to once it is registered. Ignored when it is not a site of this workspace. |
| `connectHostname` | string | No | A subdomain of the domain, such as `blog.acme.com`, to connect to that site instead of the domain itself. Ignored without `connectProjectId` or when it is not under the domain. Up to 253 characters. |