---
search:
  tags:
    - Merchant Registry
    - POST
seo:
  description: >-
    Returns the merchant and the DNS TXT record (_acceptor-verify.<domain>) to
    publish… Reference for the POST /v1/merchants endpoint in the agentsub
    Gateway API.
sidebar:
  label: Register a merchant
  badge: POST
title: Register a merchant
type: openapi-operation
---
Returns the merchant and the DNS TXT record (`_acceptor-verify.<domain>`) to publish for domain verification.

`POST /v1/merchants`

**Request body** (`application/json`, required)

- `name` (string, required)
- `domain` (string, required) — Public DNS hostname; no scheme, path, credentials, IP address or localhost
- `categories` (string[], required)

Request body example:

```json
{
  "name": "string",
  "domain": "string",
  "categories": [
    "string"
  ]
}
```

**Responses**

- `201` — Merchant registered with DNS verification record
- `400` — \`invalid\_input\` problem
- `401` — \`unauthorized\` problem; live 401s advertise \`WWW-Authenticate: Bearer resource\_metadata=...\`
- `403` — Identity, ownership, scope or policy denied (\`human\_required\`, \`owner\_claim\_required\`, \`scope\_required\`, \`FROZEN\`, \`CAP\_EXCEEDED\`, \`SCOPE\_FORBIDDEN\`)
- `503` — Runtime or provider configuration unavailable (\`runtime\_configuration\_required\`, \`signing\_configuration\_required\`, \`runtime\_unavailable\`, \`workspace\_unavailable\`, \`provider\_configuration\_required\`)

Response example, 201:

```json
{
  "merchant": {
    "id": "string",
    "ownerId": "string",
    "name": "string",
    "domain": "string",
    "verificationChallenge": "string",
    "verified": true,
    "acceptedPaymentMethods": [
      "string"
    ],
    "webhookUrl": "string"
  },
  "dnsRecord": {
    "type": "TXT",
    "name": "string",
    "value": "string"
  }
}
```