Create Customer

POST/v2/customers

Authorization

AuthorizationBearer token · headerrequired

Merchant API key scoped to one merchant and environment. Read operations require api:read, normal write operations require api:write, and broadcast mutations also require explicit broadcasts:write.

Header parameters

idempotency-keystringrequired

Required for write endpoints that create records and need deterministic retry behavior.

min length 1 · max length 255

x-request-idstring

Optional caller-provided request correlation ID.

min length 1

Request body

requiredapplication/json

namestringrequired

min length 1 · max length 160

emailstring<email>required

max length 320

mobilestringrequired

min length 8 · max length 32 · matches ^\+?[1-9]\d{7,14}$

billingAddressobject | any

default: null

Show properties

Any of:

object

line1stringrequired

min length 1 · max length 200

line2string

min length 1 · max length 200

citystringrequired

min length 1 · max length 120

regionstringrequired

min length 1 · max length 120

postalCodestringrequired

min length 1 · max length 20

countryCodestring

min length 2 · max length 2 · default: "SA"

any

any

localestring

default: "en"

Allowed:enar

externalIdstring | any

default: null

Show properties

Any of:

string

string

any

any

metadataobject

default: {}

Responses

200OK

customerobjectrequired

Show properties

idstring<uuid>required

merchantIdstring<uuid>required

environmentstringrequired

Allowed:sandboxproduction

namestring | anyrequired

Show properties

Any of:

string

string

any

any

emailstring<email>required

max length 320

mobilestring | anyrequired

Show properties

Any of:

string

string

any

any

billingAddressobject | anyrequired

Show properties

Any of:

object

line1stringrequired

min length 1 · max length 200

line2string

min length 1 · max length 200

citystringrequired

min length 1 · max length 120

regionstringrequired

min length 1 · max length 120

postalCodestringrequired

min length 1 · max length 20

countryCodeany

default: "SA"

any

any

localestringrequired

Allowed:enar

externalIdstring | anyrequired

Show properties

Any of:

string

string

any

any

emailTruststringrequired

Allowed:legacy_merchant_assertedverified

emailVerifiedAtstring<date-time> | anyrequired

Show properties

Any of:

string<date-time>

string<date-time>

any

any

statusstring

Allowed:activedeactivated

revisionintegerrequired

min -9007199254740991 · max 9007199254740991

metadataobjectrequired

createdAtstring<date-time>required

updatedAtstring<date-time>required

400Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

401Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

403Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

404Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

409Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

422Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

429Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

500Standard Cipay error response.

errorobjectrequired

Show properties

codestringrequired

min length 1

messagestringrequired

min length 1

requestIdstringrequired

min length 1

detailsobject

Request

curl -X POST "https://api.cipay.net/v2/customers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "idempotency-key: string" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string",
  "email": "<email>",
  "mobile": "string",
  "billingAddress": null,
  "locale": "en",
  "externalId": null,
  "metadata": {}
}'

const response = await fetch("https://api.cipay.net/v2/customers", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "idempotency-key": "string",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "name": "string",
  "email": "<email>",
  "mobile": "string",
  "billingAddress": null,
  "locale": "en",
  "externalId": null,
  "metadata": {}
})
});

Response

{
  "customer": {
    "id": "<uuid>",
    "merchantId": "<uuid>",
    "environment": "sandbox",
    "name": "string",
    "email": "<email>",
    "mobile": "string",
    "billingAddress": {
      "line1": "string",
      "line2": "string",
      "city": "string",
      "region": "string",
      "postalCode": "string",
      "countryCode": "SA"
    },
    "locale": "en",
    "externalId": "string",
    "emailTrust": "legacy_merchant_asserted",
    "emailVerifiedAt": "2024-01-01T00:00:00Z",
    "status": "active",
    "revision": 0,
    "metadata": {},
    "createdAt": "2024-01-01T00:00:00Z",
    "updatedAt": "2024-01-01T00:00:00Z"
  }
}