BigCommerce Docs

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.

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

dataobject

A custom domain bound to an infrastructure hosting project.

metaobject

Empty meta object.

Errors

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

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.

$	curl -X POST https://api.bigcommerce.com/stores/store_hash/v3/infrastructure/projects/project_uuid/domains \
>	-H "X-Auth-Token: <apiKey>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"domain": "shop.example.com"
>	}'

1	{
2	"data": {
3	"domain": "shop.example.com",
4	"project_uuid": "019500e2-933d-7057-8e81-090dd7240795",
5	"verification_status": "pending"
6	},
7	"meta": {}
8	}