Skip to main content
Customers represent the buyers associated with your company. You create a customer once and reuse its id (cust_...) across transactions, payments, and subscriptions. All requests require the x-api-key header. See Authentication.

​
Endpoints

MethodRouteDescription
POST/customersCreates a new customer
GET/customersLists customers (paginated, with filters)
GET/customers/:idRetrieves a customer by ID
PUT/customers/:idUpdates a customer
DELETE/customers/:idRemoves a customer (soft delete)

​
The Customer object

Fields accepted on creation (POST) and update (PUT).
​
name
string
required
Customer’s full name. Minimum of 2 characters.
​
email
string
required
Customer’s email address. Must be a valid email.
​
type
enum
required
Customer type. Accepted values: individual, company.
​
document
string
required
Customer’s identification document (CPF, CNPJ, or passport). Minimum of 6 characters.
​
documentType
enum
default:"cpf"
Document type. Accepted values: cpf, cnpj, passport. Default: cpf.
​
phone
string
required
Customer’s phone number. Cannot be empty.
​
address
object
Customer’s address (optional). All nested fields are strings and may be null.
For address, each field is required within the object but accepts null. That means: if you send address, include all 8 keys (use null for any missing values). If you have no address at all, simply omit the entire address field.

​
Create a customer

POST /customers — responds 201 Created.
Creates a new customer associated with your company. This endpoint supports idempotency: send the Idempotency-Key header with a unique value per request to avoid creating duplicate customers on retries. See Conventions.
​
x-api-key
string
required
Your API key. See Authentication.
​
Idempotency-Key
string
Unique key to ensure idempotency for the request (optional).
curl -X POST https://api.sandbox.z2pay.com/customers \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Maria Silva",
    "email": "maria.silva@example.com",
    "type": "individual",
    "document": "12345678909",
    "documentType": "cpf",
    "phone": "+5511999998888",
    "address": {
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Conjunto 101",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postalCode": "01310-100",
      "country": "BR"
    }
  }'
Resposta 201
{
  "id": "cust_8f3k2m9q1w7r5t0y",
  "name": "Maria Silva",
  "email": "maria.silva@example.com",
  "type": "individual",
  "document": "12345678909",
  "documentType": "cpf",
  "phone": "+5511999998888",
  "address": {
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "Conjunto 101",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310-100",
    "country": "BR"
  },
  "createdAt": "2026-06-24T14:30:00.000Z",
  "updatedAt": "2026-06-24T14:30:00.000Z"
}

​
List customers

GET /customers — responds 200 OK with a paginated list.
Returns the paginated list of customers for your company, with support for filters and sorting.

​
Query parameters

All filters are optional and passed as query string parameters. When provided, text values perform a partial (case-insensitive) match.
​
name
string
Filter by name.
​
email
string
Filter by email address.
​
document
string
Filter by document number.
​
documentType
enum
Filter by document type: cpf, cnpj, or passport.
​
phone
string
Filter by phone number.
​
type
enum
Filter by customer type: individual or company.
​
search
string
Free-text search.
​
customerSearch
string
Combined search (ILIKE) across name, email, and document fields.
​
startDate
string
Start of the creation date range. Format: ISO 8601 with timezone (e.g., 2026-01-01T00:00:00Z).
​
endDate
string
End of the creation date range. Format: ISO 8601 with timezone (e.g., 2026-01-31T23:59:59Z).
​
sortBy
enum
Field to sort by. Values: name, createdAt, updatedAt.
​
sortDir
enum
Sort direction. Values: asc, desc.

​
Pagination

​
page
integer
default:"1"
Page number (minimum 1).
​
limit
integer
default:"20"
Number of items per page (minimum 1, maximum 100).
Date parameters must use ISO 8601 with timezone. Date-only strings (YYYY-MM-DD) or DD/MM/YYYY format are rejected. See Conventions.
curl -G https://api.sandbox.z2pay.com/customers \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  --data-urlencode "customerSearch=maria" \
  --data-urlencode "type=individual" \
  --data-urlencode "sortBy=createdAt" \
  --data-urlencode "sortDir=desc" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=20"
Resposta 200
{
  "data": [
    {
      "id": "cust_8f3k2m9q1w7r5t0y",
      "name": "Maria Silva",
      "email": "maria.silva@example.com",
      "type": "individual",
      "document": "12345678909",
      "documentType": "cpf",
      "phone": "+5511999998888",
      "createdAt": "2026-06-24T14:30:00.000Z",
      "updatedAt": "2026-06-24T14:30:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
Pagination metadata is returned inside a pagination object (page, limit, total, and totalPages). This envelope is the platform standard — see Conventions.

​
Retrieve a customer by ID

GET /customers/:id — responds 200 OK.
Returns the full details of a specific customer.
​
id
string
required
Customer ID (e.g., cust_8f3k2m9q1w7r5t0y).
curl https://api.sandbox.z2pay.com/customers/cust_8f3k2m9q1w7r5t0y \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Resposta 200
{
  "id": "cust_8f3k2m9q1w7r5t0y",
  "name": "Maria Silva",
  "email": "maria.silva@example.com",
  "type": "individual",
  "document": "12345678909",
  "documentType": "cpf",
  "phone": "+5511999998888",
  "address": {
    "street": "Av. Paulista",
    "number": "1000",
    "complement": "Conjunto 101",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "state": "SP",
    "postalCode": "01310-100",
    "country": "BR"
  },
  "createdAt": "2026-06-24T14:30:00.000Z",
  "updatedAt": "2026-06-24T14:30:00.000Z"
}
If the customer does not exist (or has been deleted), the API responds with 404 Not Found. See the status codes reference in Errors.

​
Update a customer

PUT /customers/:id — responds 200 OK.
Updates an existing customer’s data. All fields from the Customer object are optional on update — send only the fields you want to change. This endpoint is idempotent.
​
id
string
required
ID of the customer to update.
curl -X PUT https://api.sandbox.z2pay.com/customers/cust_8f3k2m9q1w7r5t0y \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+5511988887777",
    "email": "maria.s@example.com"
  }'
Resposta 200
{
  "id": "cust_8f3k2m9q1w7r5t0y",
  "name": "Maria Silva",
  "email": "maria.s@example.com",
  "type": "individual",
  "document": "12345678909",
  "documentType": "cpf",
  "phone": "+5511988887777",
  "createdAt": "2026-06-24T14:30:00.000Z",
  "updatedAt": "2026-06-24T15:10:00.000Z"
}
If the customer does not exist, the API responds with 404 Not Found. See Errors.

​
Delete a customer

DELETE /customers/:id — responds 200 OK.
Removes a customer via soft delete: the record is not permanently erased — it is simply marked as deleted. The response returns the entity with the deletedAt field populated. This endpoint is idempotent.
​
id
string
required
ID of the customer to delete.
curl -X DELETE https://api.sandbox.z2pay.com/customers/cust_8f3k2m9q1w7r5t0y \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Resposta 200
{
  "id": "cust_8f3k2m9q1w7r5t0y",
  "name": "Maria Silva",
  "email": "maria.s@example.com",
  "type": "individual",
  "document": "12345678909",
  "documentType": "cpf",
  "phone": "+5511988887777",
  "createdAt": "2026-06-24T14:30:00.000Z",
  "updatedAt": "2026-06-24T15:10:00.000Z",
  "deletedAt": "2026-06-24T16:00:00.000Z"
}
If the customer does not exist, the API responds with 404 Not Found. See Errors.

​
See also

Transactions

Create transactions using a customer as the buyer.

Payments

Payments linked to a customer’s transactions.

Subscriptions

Recurring charges for a customer.

Conventions

Pagination, idempotency, and date formats.