Create a customer

idempotencyKey is optional — a retried request with the same key returns the original customer with 200 instead of creating a duplicate.

Authorization

apiKey

X-API-Key<token>

Your merchant API key, shown once at creation in the dashboard (Settings → API key).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

wallets?array<>

The customer's paying wallets, at most one per chain family (evm, solana). A subscription only starts billing once a wallet matching its chosen chain family is present — but you can create the customer first and add wallets later via PATCH. Sending this REPLACES the whole list.

Itemsitems <= 10

merchantReferenceId?string

Your own id for this person, for reconciliation against your systems. Lives on the customer (not the subscription) because it identifies the payer, not one purchase.

Lengthlength <= 200

email?string

Contact email. Tidepay does not email your customers — this is stored for your own use and returned on responses and webhooks.

Match^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

Formatemail

phone?Phone

Phone number in E.164 format (leading +, country code). Normalized on save so the same number is never stored twice under different local formats.

name?string

The customer's full name.

Lengthlength <= 200

dob?string

Date of birth as YYYY-MM-DD. Date only — a birthdate has no time-of-day component.

Match^\d{4}-\d{2}-\d{2}$

pob?string

Place of birth, free text (city/country). No fixed taxonomy.

Lengthlength <= 200

address?

Structured postal address. Stored as fields rather than one blob so it can be reused for invoicing and compliance.

idempotencyKey?string

Your own key for this logical operation. Retrying with the same key returns the ORIGINAL customer with 200 instead of creating a duplicate. Scoped per merchant and per live/test mode.

Length1 <= length <= 200

Response Body

`application/json`

curl -X POST "https://example.com/customers" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "cust_01j8x2q3r4s5t6u7v8w9x0y1z2",  "wallets": [    {      "chainFamily": "evm",      "address": "0x71c7656ec7ab88b098defb751b7401b5f6d8976"    }  ],  "merchantReferenceId": "string",  "email": "string",  "phone": "string",  "name": "string",  "createdAt": "2026-08-19T14:32:00.000Z",  "updatedAt": "2026-08-19T14:32:00.000Z",  "merchantId": "string",  "isSandbox": true,  "idempotencyKey": "string"}

Create a customer

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

409application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`