Domains API

The Domains API lets you read and manage the custom store domains registered on your Snipcart account: your default website domain plus the list of additional allowed domains and subdomains the cart widget is permitted to run on. (This is not the email/SendGrid sending-domain configuration.)

Requests are authenticated with your secret API key, sent as the HTTP Basic username with an empty password. With curl: -u {API_KEY}:. See Authentication for details. The base URL for every request is https://app.snipcart.com/api.

Table of contents

GET /settings/domain

Returns your account's current default domain.

Resource URL

GET https://app.snipcart.com/api/settings/domain

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts the application/json content type, so you must specify the Accept: application/json header in every request.

Example request 

curl -H "Accept: application/json" \
  https://app.snipcart.com/api/settings/domain \
  -u {API_KEY}:

Example response 

{
  "domain": "snipcart.com",
  "protocol": "https"
}

PUT /settings/domain

Sets your account's default domain to the one specified in the request body. The submitted domain is normalized to its bare hostname (any scheme, path, or www. prefix is stripped). If protocol is omitted or is not exactly http or https, it defaults to http.

Resource URL

PUT https://app.snipcart.com/api/settings/domain

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts the application/json content type, so you must specify the Accept: application/json header in every request.
Content-Type application/json Yes The request body is JSON, so the content type must be specified.

Body Parameters

Name Required? Type Description
domain Yes string The new default domain to associate with your account.
protocol No string Either https or http. If omitted or set to any other value, defaults to http.

⚠️ Important: If domain is missing from the body, the request returns 400 Bad Request.

Example request 

curl https://app.snipcart.com/api/settings/domain \
  -X PUT \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -u {API_KEY}: \
  -d '{"domain": "snipcartnewdomain.com", "protocol": "https"}'

Example response 

{
  "domain": "snipcartnewdomain.com",
  "protocol": "https"
}

GET /settings/alloweddomains

Returns the list of allowed domains and subdomains registered on the account, other than your default website domain.

Resource URL

GET https://app.snipcart.com/api/settings/alloweddomains

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts the application/json content type, so you must specify the Accept: application/json header in every request.

Example request 

curl -H "Accept: application/json" \
  https://app.snipcart.com/api/settings/alloweddomains \
  -u {API_KEY}:

Example response 

[
  {
    "domain": "15ddef3a.ngrok.io",
    "protocol": "http"
  },
  {
    "domain": "subdomain.snipcart.com",
    "protocol": "https"
  }
]

POST /settings/alloweddomains

Adds one or more domains or subdomains to the account's allowed-domains list. The body must be a JSON array, even when adding a single domain. Each domain is normalized to its bare hostname, and any protocol other than http or https is coerced to http.

The response returns the full, updated list of allowed domains (the newly added ones plus those already registered). Your default website domain is never included in this list.

Resource URL

POST https://app.snipcart.com/api/settings/alloweddomains

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts the application/json content type, so you must specify the Accept: application/json header in every request.
Content-Type application/json Yes The request body is JSON, so the content type must be specified.

Body Parameters

Name Required? Type Description
(root) Yes array A JSON array of { "domain": "...", "protocol": "..." } objects. The array wrapper is required even for a single entry.
domain Yes string The domain or subdomain to add.
protocol No string Either https or http. If omitted or set to any other value, defaults to http.

⚠️ Important: An empty or missing array returns 400 Bad Request.

Example request 

curl https://app.snipcart.com/api/settings/alloweddomains \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u {API_KEY}: \
  -d '[{"domain": "subdomain1.snipcart.com"}, {"domain": "snipalt.com", "protocol": "https"}]'

Example response 

[
  {
    "domain": "subdomain1.snipcart.com",
    "protocol": "http"
  },
  {
    "domain": "snipalt.com",
    "protocol": "https"
  },
  {
    "domain": "subdomain.snipcart.com",
    "protocol": "https"
  }
]

DELETE /settings/alloweddomains

Removes one or more domains or subdomains from the account's allowed-domains list. The body must be a JSON array, even when removing a single domain. Matching is done on the domain value (normalized to its bare hostname).

The response returns the full, updated list of allowed domains after the removals. Your default website domain is never included in this list.

Resource URL

DELETE https://app.snipcart.com/api/settings/alloweddomains

Headers

Name Value Required? Description
Accept application/json Yes Our API only accepts the application/json content type, so you must specify the Accept: application/json header in every request.
Content-Type application/json Yes The request body is JSON, so the content type must be specified.

Body Parameters

Name Required? Type Description
(root) Yes array A JSON array of { "domain": "...", "protocol": "..." } objects. The array wrapper is required even for a single entry.
domain Yes string The domain or subdomain to remove.
protocol No string Optional; only domain is used to match entries for removal.

⚠️ Important: If any domain in the body is not currently in the allowed list, the entire request fails with 400 Bad Request and nothing is removed. An empty or missing array also returns 400 Bad Request.

Example request 

curl https://app.snipcart.com/api/settings/alloweddomains \
  -X DELETE \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -u {API_KEY}: \
  -d '[{"domain": "subdomain1.snipcart.com"}, {"domain": "snipalt.com", "protocol": "https"}]'

Example response 

[
  {
    "domain": "subdomain.snipcart.com",
    "protocol": "https"
  }
]

Was this article helpful?