Create Customer

Creates a new customer for the authenticated merchant.

This API supports:

Creating a customer with an email and/or a phone number
Associating the customer with a storeId or a tpn
Validating that the storeId and tpn belong to the authenticated merchant
Detecting duplicate customers and returning every matching customer

Header Parameters

token*string

Authentication token generated using the API Key and Secret Key using an Merchant Account. Required for all API requests.

Idempotency-Key?string

A Unique key generated for each operation to prevent duplicate processing when retrying requests. A UUID is recommended. The key must contain 1–255 visible ASCII characters. If the same request is retried with the same key within 24 hours, the API returns the original successful response with the header 'Idempotent-Replayed: true' instead of processing the operation again

Length1 <= length <= 255

Request Body

application/json

customer_externalRefId?|

Your own reference for this customer (for example, a CRM ID). Letters, numbers, underscore and hyphen only, up to 100 characters.

Lengthlength <= 100

email?|

Standard email address using English letters, digits and the usual symbols. Stored and returned in lower case. Either email or phone must be provided.

Formatemail

Lengthlength <= 254

phone?|

International (E.164) format with + and country code, for example +14045550123. Any country code is accepted; only the format (digits and length) is checked, the number itself is not verified. Either email or phone must be provided.

firstName*string

Customer first name, 2–25 characters. Letters, digits, space, period and apostrophe.

Length2 <= length <= 25

lastName?|

Customer last name, 1–25 characters. Letters, digits, space, period and apostrophe.

Length1 <= length <= 25

Dba?|

DBA name, 2–25 characters. Letters, digits, space, period, apostrophe and _ $ , - @ &.

Length2 <= length <= 25

Zipcode?|

5, 6 or 9 letters/digits; a 6-character ZIP is stored as A1B 2C3. No hyphen (12345-6789 is rejected; send 123456789). When sent, City and State are required.

City?|

Letters and spaces, starting with a letter. Required when Zipcode is sent; not accepted without it. Ignored when the ZIP is found in Get Zipcodes.

Lengthlength <= 255

State?|

Letters only, for example GA. Required when Zipcode is sent; not accepted without it. Ignored when the ZIP is found in Get Zipcodes.

Lengthlength <= 255

storeId?|

12-character public store ID of an ACTIVE store, from Get Store ID. Associates the customer with this store; the store is persisted on the customer.

Refer to Get Store ID to find the store ID.

Response Body

`application/json`

curl -X POST "https://example.com" \  -H "token: your-access-token-here" \  -H "Idempotency-Key: 5f0c8e4a-2b7d-4c1e-9a3f-1d2e3f4a5b6c" \  -H "Content-Type: application/json" \  -d '{    "customer_externalRefId": "CRM-4632357",    "email": "docs.full.4632357@example.com",    "phone": "+14044632357",    "firstName": "Jane",    "lastName": "Doe",    "Dba": "Jane Bakery",    "Zipcode": "30301",    "City": "Atlanta",    "State": "GA",    "storeId": "05cbaac8502f"  }'

{
  "data": {
    "customer_id": "LMPD9SWTTI1LI05",
    "customer_externalRefId": "CRM-4632357",
    "email": "docs.full.4632357@example.com",
    "phone": "+14044632357",
    "firstName": "Jane",
    "lastName": "Doe",
    "Dba": "Jane Bakery",
    "Zipcode": "30301",
    "City": "Atlanta",
    "State": "GA",
    "storeId": "05cbaac8502f"
  },
  "message": "Customer created successfully",
  "response_code": "SUCCESS",
  "status_code": 201,
  "request_id": "TEST-20261008183354-MDQYGU",
  "timestamp": "2026-10-08T13:03:54.158Z"
}

{
  "data": null,
  "message": "The request contains invalid input parameters.",
  "response_code": "BAD_REQUEST",
  "status_code": 400,
  "request_id": "TEST-20261012160432-XQGE3D",
  "timestamp": "2026-10-12T10:34:32.432Z",
  "errors": [
    {
      "field": "Zipcode",
      "messages": [
        "Zipcode must be 5, 6 or 9 letters/digits (6 may be written as A1B 2C3); no other characters"
      ]
    }
  ]
}

{
  "data": null,
  "message": "Missing authentication token. Please include a valid API token in your request.",
  "response_code": "TOKEN_MISSING",
  "status_code": 401,
  "request_id": "TEST-20261022075139-8WQOJH",
  "timestamp": "2026-10-22T07:51:39.690Z"
}

{
  "data": null,
  "message": "Store not found",
  "response_code": "NOT_FOUND",
  "status_code": 404,
  "request_id": "TEST-20261008183411-IXFQJL",
  "timestamp": "2026-10-08T13:04:11.604Z"
}

{
  "data": null,
  "message": "Store ID is ambiguous, send tpn instead",
  "response_code": "CONFLICT",
  "status_code": 409,
  "request_id": "TEST-20261008183414-EFGBWX",
  "timestamp": "2026-10-08T13:04:14.622Z"
}

{
  "data": null,
  "message": "Unsupported content type",
  "response_code": "BAD_REQUEST",
  "status_code": 415,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>",
  "errors": [
    {
      "field": "body",
      "messages": [
        "Content-Type must be application/json"
      ]
    }
  ]
}

{
  "data": null,
  "message": "This Idempotency-Key was already used with a different request",
  "response_code": "BAD_REQUEST",
  "status_code": 422,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}

{
  "data": null,
  "message": "Too many requests, please try again in a minute",
  "response_code": "RATE_LIMITED",
  "status_code": 429,
  "timestamp": "<ISO 8601 time>"
}

{
  "data": null,
  "message": "An error occurred while processing your request. Please try again later.",
  "response_code": "INTERNAL_ERROR",
  "status_code": 500,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}

{
  "data": null,
  "message": "Idempotency check is temporarily unavailable, please retry",
  "response_code": "SERVICE_UNAVAILABLE",
  "status_code": 503,
  "request_id": "<generated per request>",
  "timestamp": "<ISO 8601 time>"
}

Create Customer

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

404application/json

409application/json

415application/json

422application/json

429application/json

500application/json

503application/json

ZIP with a hyphen (12345-6789) is rejected; send 123456789

Neither email nor phone

firstName missing

firstName too short

firstName/lastName with invalid characters

Invalid email

Invalid phone

Zipcode wrong length

storeId wrong format

customer_externalRefId with invalid characters

Dba too short

Unknown field

Several invalid fields at once

Malformed JSON body

customer_externalRefId not a string

customer_externalRefId longer than 100

email not a string

email longer than 254

phone not a string

firstName empty

firstName not a string

firstName longer than 100

lastName longer than 100

lastName not a string

Dba longer than 100

Dba with invalid characters

Dba not a string

Zipcode not a string

storeId not a string

Body is a JSON array

Body sent as text/plain

phone without + and country code

Body with a __proto__ key

Body is JSON but not an object (e.g. null)

Body nested more than 32 levels

Zipcode without City and State

Zipcode and City without State

City / State without Zipcode

City with characters other than letters and spaces

State with a space (letters only)

City longer than 255 characters

Idempotency-Key empty, too long or with non-ASCII / space characters

token header missing

Invalid token

storeId of another merchant

Expired token

Token could not be verified

Token revoked or inactive

Token is not a MERCHANT or STORE token

Account is inactive (message starts with MERCHANT or STORE)

storeId that does not exist

Deactivated store

storeId shared by more than one store

Same email under the same store

Same email and same phone

Same email, different phone

Same phone, different email

Email matches one customer and phone matches another

Same Idempotency-Key while the first request is still running

Unexpected server error

Error while verifying the token

Auth public key not configured on the server

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`