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

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

### Response (no domain connected)

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

### Response (domain connected)

```json
{
  "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

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `domain` | `string` | Yes | Custom domain to connect, e.g. `example.com` or `shop.example.com` (no protocol or path) |

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

```json
{
  "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"
      }
    ]
  }
}
```

| Status | Meaning |
|--------|---------|
| `400` | Invalid domain, or store has no builder project (not AI-built) |
| `409` | Domain already in use or pending verification on another project |
| `502` | Failed to attach the domain with Vercel |

---

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

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

### Response (200)

```json
{
  "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`.

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

### Response (200)

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