> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iterapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Merchant — POST /merchants

> Create a new merchant account under your organization. Returns the new merchant's UUID on success. Requires Bearer token authentication.

The Create Merchant endpoint creates a new merchant account. Merchants are the top-level container for invoices, balances, API keys, and settings in IteraPay. You must authenticate with a Bearer token — API keys cannot be used to create new merchants.

**`POST /merchants`**

## Authentication

Requires a Bearer token (`Authorization: Bearer <token>`). API key authentication is not accepted for this endpoint.

## Request body

<ParamField body="name" type="string" required>
  The display name for the new merchant. This name appears in the dashboard and on invoices.
</ParamField>

## Response fields

A `201 Created` response is returned on success.

<ResponseField name="id" type="string" required>
  The UUID of the newly created merchant.
</ResponseField>

## Example request

```bash theme={null}
curl --request POST \
  --url https://api.iterapay.com/merchants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Store"
  }'
```

## Example response

```json theme={null}
{
  "id": "b0fcc813-a7ce-4bbc-932f-dbef6f59ca7f"
}
```

## Error responses

| Status | Description                                                              |
| ------ | ------------------------------------------------------------------------ |
| `400`  | Invalid request body. The `detail` field describes the validation error. |
| `401`  | Missing or invalid Bearer token.                                         |
| `403`  | Valid credentials but insufficient permissions to create a merchant.     |