Add a Domain

Beta

POST

https://api.bigcommerce.com/stores/:store_hash/v3/infrastructure/projects/:project_uuid/domains

Adds a custom domain to a project. Adding a domain triggers DNS verification and binds the domain in the routing layer. The domain starts in the pending verification status until DNS propagation and hostname validation completes.

The response’s data.pointing_records object contains the DNS records that point the domain at the project: use the CNAME record value for a subdomain, or the A record value for an apex domain. This is the only endpoint that returns the pointing records, so store them before moving on. The Get a Domain and List Domains endpoints don’t return them.

If the domain is already bound to a different store, this endpoint returns a 409 Conflict whose meta.ownership_verification contains the TXT record you must publish before claiming the domain with the Claim a Domain endpoint.

Adds a custom domain to a project. Adding a domain triggers DNS verification and binds the domain in the routing layer. The domain starts in the `pending` verification status until DNS propagation and hostname validation completes. The response's `data.pointing_records` object contains the DNS records that point the domain at the project: use the `CNAME` record value for a subdomain, or the `A` record value for an apex domain. This is the only endpoint that returns the pointing records, so store them before moving on. The [Get a Domain](#get-a-domain) and [List Domains](#list-domains) endpoints don't return them. If the domain is already bound to a different store, this endpoint returns a `409 Conflict` whose `meta.ownership_verification` contains the TXT record you must publish before claiming the domain with the [Claim a Domain](#claim-a-domain) endpoint.

Authentication

X-Auth-Tokenstring

OAuth scopes

UI Name	Permission	Parameter
Infrastructure Deployments	read-only	`store_infrastructure_deployments_read_only`
Infrastructure Deployments	create preview	`store_infrastructure_deployments_create_preview`
Infrastructure Deployments	manage	`store_infrastructure_deployments_manage`
Infrastructure Projects	read-only	`store_infrastructure_projects_read_only`
Infrastructure Projects	manage	`store_infrastructure_projects_manage`
Infrastructure Logs	read-only	`store_infrastructure_logs_read_only`

Authentication header

Header	Argument	Description
`X-Auth-Token`	`access_token`	For more about API accounts that generate `access_token`s, see our Guide to API Accounts.

### OAuth scopes | UI Name | Permission | Parameter | |:--------|:-----------|:----------| | Infrastructure Deployments | read-only | `store_infrastructure_deployments_read_only` | | Infrastructure Deployments | create preview | `store_infrastructure_deployments_create_preview` | | Infrastructure Deployments | manage | `store_infrastructure_deployments_manage` | | Infrastructure Projects | read-only | `store_infrastructure_projects_read_only` | | Infrastructure Projects | manage | `store_infrastructure_projects_manage` | | Infrastructure Logs | read-only | `store_infrastructure_logs_read_only` | ### Authentication header | Header | Argument | Description | |:-------|:---------|:------------| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/developer/docs/overview/api-fundamentals/api-accounts#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/developer/api-reference/rest/overview#rest-http-status-codes).

Path parameters

project_uuidstringRequiredformat: "uuid"

The UUID of the project to add the domain to.

store_hashstringRequired

Permanent ID of the BigCommerce store.

Request

This endpoint expects an object.

domainstringRequired

The custom domain name to add to the project.

Response

The domain was added successfully.

dataobjectOptional

A custom domain bound to an infrastructure hosting project.

metaobjectOptional

Empty meta object.

Errors

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error