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

# Create Outlet

> Create an outlet (agent or sub-business) under your merchant account

> [!NOTE]
>
> **Auth method: Signed (HMAC)** — this endpoint requires the full set of signed
> headers: `x-access-id`, `x-request-id`, `x-timestamp`, and an HMAC-SHA256
> `authorization` signature. See [Authentication](/api-reference/authentication.md#signed-hmac-authentication).

Creates an outlet (also called an agent or sub-business) under your merchant account. Outlets let
you separate sales by store, channel or team, each with its own default fiat currency.

You can create two outlet types through the API:

| `type` | Use for | Required fields |
| - | - | - |
| `online` (default) | A website, app or other online integration | `name`, `location`, `country`, `outletIntent` |
| `whatsapp` | A WhatsApp sales channel | `name`, `phoneNumber`, `outletIntent: "Whatsapp"` |

> [!NOTE]
>
> Physical point-of-sale (`pos`) outlets can't be created through the API. Create them from the
> Tender merchant dashboard.

Agent endpoints share a limit of 120 requests per minute. See [Rate limits](/api-reference/rate-limits.md).

## Headers

**authorization** `string` *required*

Base64-encoded HMAC-SHA256 signature of `{"timeStamp":"<x-timestamp>","requestId":"<x-request-id>","accessId":"<x-access-id>"}`, signed with your access secret. The request body is not part of the signature.

**Example:** `"pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0="`

**x-timestamp** `string` *required*

ISO 8601 timestamp; must be within 5 minutes of server time

**Example:** `"2026-10-15T09:45:53.000Z"`

**x-request-id** `string` *required*

A unique UUID v4 per request

**Example:** `"550e8400-e29b-41d4-a716-446655440000"`

**x-access-id** `string` *required*

Your API access ID provided by Tender

**Example:** `"your-access-id-here"`

**Content-Type** `string` *required*

Media type of the request body

**Example:** `"application/json"`

## Body

**type** `string` (default: online)

Outlet type: `online` or `whatsapp`. Defaults to `online`.

**Example:** `"online"`

**name** `string` *required*

Display name of the outlet

**Example:** `"Lagos Fashion Store"`

**outletIntent** `string`

How the outlet will be used. **Required for `online` and `whatsapp` outlets.** One of
`Woocommerce`, `Webhook`, `API integration`, `Shopify`, `Wix`, `Squarespace` or `Whatsapp`.
For `whatsapp` outlets it must be `Whatsapp`.

**Example:** `"API integration"`

**location** `string`

Location of the outlet. **Required for `online` outlets.**

**Example:** `"Lagos"`

**country** `string`

Country of the outlet. **Required for `online` outlets.**

**Example:** `"Nigeria"`

**phoneNumber** `string`

Phone number in E.164 format: a `+`, the country code and the number, with no spaces.
**Required for `whatsapp` outlets**, and each WhatsApp number can belong to only one outlet.
Optional for `online` outlets, but must be E.164 if sent.

**Example:** `"+2348012345678"`

**email** `string`

Email address of the outlet. Optional. Must be unique: an email already used by another outlet
is rejected.

**Example:** `"lagosfashion@store.com"`

**currency** `string` (default: USD)

The outlet's default fiat currency. Payments initiated for this outlet are priced in it. Must be a
fiat currency Tender supports (see [Fetch All Currencies](/api-reference/endpoint/fetch-currencies.md)
with `type=fiat`). Defaults to `USD`.

**Example:** `"NGN"`

**avatar** `string`

URL of the outlet's avatar image. Optional.

**Example:** `"https://example.com/avatar.png"`

String fields are limited to 500 characters and may not contain `$ \ ( ) < >`.

## Response

**status** `string` *required*

Status of the API request

**Example:** `"success"`

**message** `string` *required*

Human-readable message describing the result

**Example:** `"success"`

**data** `object` *required*

The new outlet

**data properties**

**id** `string`

Outlet ID

**Example:** `"66f33b1fa9446a6b6b8f32cd"`

**reference** `string`

The outlet's Tender reference code

**Example:** `"vbibtucm9ynq3k2x7p"`

**name** `string`

Display name of the outlet

**Example:** `"Lagos Fashion Store"`

**type** `string`

Outlet type

**Example:** `"online"`

**email** `string`

Email address, lowercased. Omitted if none was sent.

**Example:** `"lagosfashion@store.com"`

**phoneNumber** `string`

Phone number. Omitted if none was sent.

**Example:** `"+2348012345678"`

**location** `string`

Location of the outlet

**Example:** `"Lagos"`

**country** `string`

Country of the outlet

**Example:** `"Nigeria"`

**active** `boolean`

Whether the outlet is active

**Example:** `true`

**merchantId** `string`

ID of your merchant account

**Example:** `"6538e8f9bdec6d1a21978a64"`

**currency** `string`

The outlet's default fiat currency

**Example:** `"NGN"`

**totalSales** `string`

Total sales. `"0"` for a new outlet.

**Example:** `"0"`

**defaultFiatCurrency** `object`

Default fiat currency settings

**defaultFiatCurrency properties**

**currency** `string`

Fiat currency code

**Example:** `"NGN"`

**rate** `string`

Fiat units per USD at creation

**Example:** `"1500"`

**useSystemRate** `boolean`

Whether payments use Tender's live exchange rate. Always `true` for outlets created
through the API.

**Example:** `true`

**createdAt** `string`

ISO 8601 timestamp when the outlet was created

**Example:** `"2026-10-15T09:45:53.000Z"`

## Errors

All errors return HTTP 400.

| Message | Cause |
| - | - |
| `phoneNumber must include a valid country code` | `phoneNumber` isn't in E.164 format |
| `outletIntent must be a string` / `outletIntent must be one of the following values: …` | `outletIntent` is missing or not an allowed value |
| `location must be a string` / `country must be a string` | Missing `location` or `country` on an `online` outlet |
| `Select WhatsApp as the social channel` | A `whatsapp` outlet without `outletIntent: "Whatsapp"` |
| `WhatsApp number is linked to another outlet. Use a different number.` | The WhatsApp number is already in use |
| `Agent Already exists` / `Email Already taken` | The email is already used by an outlet |
| `Currency is not supported` | `currency` isn't a supported fiat currency |

## Example request

```bash theme={null}
curl -X POST https://sandbox-api.tender.cash/v1/api/agent/create \
  -H "Content-Type: application/json" \
  -H "x-access-id: your-access-id-here" \
  -H "x-request-id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "x-timestamp: 2026-10-15T09:45:53.000Z" \
  -H "authorization: pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0=" \
  -d '{
    "type": "online",
    "name": "Lagos Fashion Store",
    "email": "lagosfashion@store.com",
    "location": "Lagos",
    "country": "Nigeria",
    "currency": "NGN",
    "outletIntent": "API integration"
  }'
```

## Example response

```json theme={null}
{
  "status": "success",
  "message": "success",
  "data": {
    "id": "66f33b1fa9446a6b6b8f32cd",
    "name": "Lagos Fashion Store",
    "email": "lagosfashion@store.com",
    "country": "Nigeria",
    "location": "Lagos",
    "type": "online",
    "active": true,
    "reference": "vbibtucm9ynq3k2x7p",
    "merchantId": "6538e8f9bdec6d1a21978a64",
    "currency": "NGN",
    "totalSales": "0",
    "defaultFiatCurrency": {
      "currency": "NGN",
      "rate": "1500",
      "useSystemRate": true
    },
    "createdAt": "2026-10-15T09:45:53.000Z"
  }
}
```


## OpenAPI

````yaml POST /v1/api/agent/create
openapi: 3.1.0
info:
  title: Tender API
  description: Tender Developer API for cryptocurrency payments and agent management
  version: 2.0.0
  contact:
    name: Tender Support
    url: https://tender.cash
servers:
  - url: https://secureapi.tender.cash
    description: Production Server
  - url: https://sandbox-api.tender.cash
    description: Sandbox Server
security:
  - SignedAuth: []
tags:
  - name: Agents
    description: Manage agents and sub-businesses
  - name: Transactions
    description: Payment and transaction operations
  - name: System
    description: System information and configuration
  - name: Webhooks
    description: Webhook management and logs
  - name: On-ramp
    description: Fiat-to-crypto on-ramp operations
  - name: Payouts
    description: Send crypto from merchant balance to a wallet address or payout account
  - name: Subwallets
    description: Provision and manage crypto wallet infrastructure for your end-users
  - name: Conversions
    description: Swap crypto between coins and chains, or convert to a payout account
paths:
  /v1/api/agent/create:
    post:
      tags:
        - Agents
      summary: Create Outlet
      description: >-
        Create an `online` or `whatsapp` outlet (agent). POS outlets are created
        from the dashboard.
      operationId: createAgent
      parameters:
        - name: authorization
          in: header
          required: true
          description: >-
            Base64-encoded HMAC-SHA256 signature of
            `{"timeStamp":"<x-timestamp>","requestId":"<x-request-id>","accessId":"<x-access-id>"}`,
            signed with your access secret. The request body is not part of the
            signature.
          schema:
            type: string
          example: pV3n0o8kq0lK2mJ8bZ1yq3Yt6hR0cXK9u4mVJ2l9sE0=
        - name: x-timestamp
          in: header
          required: true
          description: ISO 8601 timestamp; must be within 5 minutes of server time
          schema:
            type: string
            format: date-time
          example: '2026-10-15T09:45:53.000Z'
        - name: x-request-id
          in: header
          required: true
          description: A unique UUID v4 per request
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        - name: x-access-id
          in: header
          required: true
          description: Your API access ID provided by Tender
          schema:
            type: string
          example: your-access-id-here
        - name: Content-Type
          in: header
          required: true
          description: Media type of the request body
          schema:
            type: string
          example: application/json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
            example:
              type: online
              name: Lagos Fashion Store
              email: lagosfashion@store.com
              location: Lagos
              country: Nigeria
              currency: NGN
              outletIntent: API integration
      responses:
        '200':
          description: Outlet created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '400':
          description: >-
            Validation error, duplicate email or WhatsApp number, or unsupported
            currency
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsErrorResponse'
              example:
                status: error
                message: phoneNumber must include a valid country code
                data: null
        '401':
          description: >-
            Missing headers, bad signature or timestamp outside the 5-minute
            window
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsErrorResponse'
              example:
                status: error
                message: INVALID_REQUEST_SIGNATURE
                data: {}
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentsErrorResponse'
              example:
                status: error
                message: Too many requests. Max 120 per 60s.
                data: null
      security:
        - SignedAuth: []
components:
  schemas:
    CreateAgentRequest:
      type: object
      required:
        - name
      description: >-
        `online` outlets require location, country and outletIntent. `whatsapp`
        outlets require phoneNumber and outletIntent `Whatsapp`. POS outlets are
        created from the dashboard.
      properties:
        type:
          type: string
          enum:
            - online
            - whatsapp
          default: online
        name:
          type: string
          maxLength: 500
          example: Lagos Fashion Store
        outletIntent:
          type: string
          enum:
            - Woocommerce
            - Webhook
            - API integration
            - Shopify
            - Wix
            - Squarespace
            - Whatsapp
          example: API integration
        location:
          type: string
          maxLength: 500
          example: Lagos
        country:
          type: string
          maxLength: 500
          example: Nigeria
        phoneNumber:
          type: string
          pattern: ^\+[1-9]\d{7,14}$
          description: E.164
          example: '+2348012345678'
        email:
          type: string
          format: email
          maxLength: 500
          example: lagosfashion@store.com
        currency:
          type: string
          default: USD
          example: NGN
        avatar:
          type: string
          maxLength: 500
    AgentResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: success
        data:
          $ref: '#/components/schemas/Agent'
    PaymentsErrorResponse:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
        data:
          nullable: true
          description: Usually `null` or `{}`
    Agent:
      type: object
      properties:
        id:
          type: string
          example: 66f33b1fa9446a6b6b8f32cd
        reference:
          type: string
          example: vbibtucm9ynq3k2x7p
        name:
          type: string
          example: Lagos Fashion Store
        type:
          type: string
          description: Returned by create only
          example: online
        email:
          type: string
        phoneNumber:
          type: string
        location:
          type: string
        country:
          type: string
        active:
          type: boolean
        merchantId:
          type: string
        currency:
          type: string
          example: NGN
        totalSales:
          type: string
          example: '0'
        defaultFiatCurrency:
          type: object
          properties:
            currency:
              type: string
            rate:
              type: string
            useSystemRate:
              type: boolean
        createdAt:
          type: string
          format: date-time
  securitySchemes:
    SignedAuth:
      type: apiKey
      in: header
      name: authorization
      description: >-
        Signed (HMAC) authentication. Required headers: x-access-id,
        x-request-id (UUID v4), x-timestamp (ISO 8601, must be within 5 minutes
        of server time), and authorization: the Base64 HMAC-SHA256 of the JSON
        string
        {"timeStamp":"<x-timestamp>","requestId":"<x-request-id>","accessId":"<x-access-id>"}
        (keys in that order, no whitespace) using your access secret. The
        request body, method and path are not signed. The API key must be linked
        to an outlet.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.