Domain API

REST API endpoints for connecting and verifying a custom domain.

Connect a custom domain to your store, fetch the DNS records to set at your registrar, and re-check verification. Custom domains attach to the store's builder (Vercel) project, so these endpoints only work for AI-built stores. Domain purchasing is not exposed through the API.

The status field is one of: No Domain, Pending Verification, Valid Configuration, Invalid Configuration, Domain Not Found, or Unknown Error.

Get Domain Status

GET /api/v1/domain

Returns the connected custom domain and its DNS/verification status. When a domain is connected, dns.record is the apex A record (or subdomain CNAME) to set, and dns.verification holds Vercel's ownership-challenge records (present until the domain verifies).

curl \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/domain

Response (no domain connected)

{
  "domain": null,
  "status": "No Domain",
  "verified": false,
  "dns": null
}

Response (domain connected)

{
  "domain": "shop.example.com",
  "status": "Pending Verification",
  "verified": false,
  "dns": {
    "record": {
      "type": "CNAME",
      "name": "shop",
      "value": "cname.vercel-dns.com"
    },
    "verification": [
      {
        "type": "TXT",
        "domain": "_vercel.example.com",
        "value": "vc-domain-verify=shop.example.com,abc123def456"
      }
    ]
  }
}

Connect Domain

POST /api/v1/domain

Attaches a custom domain to the store's builder project and returns the DNS records the owner must set. For an apex domain (example.com) this is an A record at @; for a subdomain (shop.example.com) it is a CNAME. Re-running with a different domain detaches the previous one first.

Request Body

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"domain": "shop.example.com"}' \
  https://your-store.yns.store/api/v1/domain

Response (200)

Returns the same shape as GET /api/v1/domain, with the DNS records to set.

{
  "domain": "shop.example.com",
  "status": "Pending Verification",
  "verified": false,
  "dns": {
    "record": {
      "type": "CNAME",
      "name": "shop",
      "value": "cname.vercel-dns.com"
    },
    "verification": [
      {
        "type": "TXT",
        "domain": "_vercel.example.com",
        "value": "vc-domain-verify=shop.example.com,abc123def456"
      }
    ]
  }
}

Verify Domain

POST /api/v1/domain/verify

Asks Vercel to re-verify the connected domain's DNS and returns the current status (same shape as GET /api/v1/domain). Call this after setting the DNS records to check whether the domain has verified.

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/domain/verify

Response (200)

{
  "domain": "shop.example.com",
  "status": "Valid Configuration",
  "verified": true,
  "dns": {
    "record": {
      "type": "CNAME",
      "name": "shop",
      "value": "cname.vercel-dns.com"
    },
    "verification": []
  }
}

A 400 is returned when no custom domain is connected to verify.

Remove Domain

DELETE /api/v1/domain

Detaches the custom domain from the Vercel project and clears it from the store. Idempotent — removing when no domain is connected still returns 200.

curl -X DELETE \
  -H "Authorization: Bearer your_api_key" \
  https://your-store.yns.store/api/v1/domain

Response (200)

{
  "ok": true,
  "domain": null
}