List Customers

GET/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.

Query parameters

querystring

min length 1 · max length 160

externalIdstring

min length 1 · max length 160

subscriptionstring

Allowed:trialingactiverenewinggrace_periodpast_duecancelednone

paymentstring

Allowed:succeededfailedmissing_payment_method

createdFromstring<date-time>

createdTostring<date-time>

limitinteger

min 1 · max 100 · default: 25

cursorstring

matches ^\d+$

Header parameters

x-request-idstring

Optional caller-provided request correlation ID.

min length 1

Responses

200OK

customersobject[]required

Show properties

Array of object

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

createdAtstring<date-time>required

updatedAtstring<date-time>required

displayNamestring | any

Show properties

Any of:

string

string

any

any

avatarUrlstring<uri> | any

Show properties

Any of:

string<uri>

string<uri>

any

any

orderCountintegerrequired

min 0 · max 9007199254740991

subscriptionCountintegerrequired

min 0 · max 9007199254740991

activeSubscriptionCountintegerrequired

min 0 · max 9007199254740991

metricsobjectrequired

Show properties

mrrHalalasintegerrequired

min 0 · max 9007199254740991

revenueHalalasintegerrequired

min 0 · max 9007199254740991

grossCashHalalasintegerrequired

min 0 · max 9007199254740991

vatCollectedHalalasintegerrequired

min 0 · max 9007199254740991

refundedHalalasintegerrequired

min 0 · max 9007199254740991

refundedTaxableHalalasintegerrequired

min 0 · max 9007199254740991

refundedVatHalalasintegerrequired

min 0 · max 9007199254740991

netCashHalalasintegerrequired

min 0 · max 9007199254740991

nextCursorstring | anyrequired

Show properties

Any of:

string

string

any

any

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 GET "https://api.cipay.net/v2/customers" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.cipay.net/v2/customers", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

Response

{
  "customers": [
    {
      "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,
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "displayName": "string",
      "avatarUrl": "<uri>",
      "orderCount": 0,
      "subscriptionCount": 0,
      "activeSubscriptionCount": 0,
      "metrics": {
        "mrrHalalas": 0,
        "revenueHalalas": 0,
        "grossCashHalalas": 0,
        "vatCollectedHalalas": 0,
        "refundedHalalas": 0,
        "refundedTaxableHalalas": 0,
        "refundedVatHalalas": 0,
        "netCashHalalas": 0
      }
    }
  ],
  "nextCursor": "string"
}