Customers API

Create, read, update, and delete customers in your store.

Endpoints

GET

/customers

customers:read

Retrieve a paginated list of customers.

GET

/customers/:id

customers:read

Retrieve a single customer by their ID.

POST

/customers

customers:write

Create a new customer.

PUT

/customers/:id

customers:write

Update an existing customer. Partial updates are supported.

DELETE

/customers/:id

customers:write

Soft-delete a customer. The record can be restored within 30 days.

Field Reference

Field	Type	Required	Description
id	string	No	Unique customer identifier (read-only)
name	string	Yes	Customer full name
email	string	Yes	Customer email address
phone	string	No	Phone number with country code
createdAt	datetime	No	ISO 8601 timestamp (read-only)
updatedAt	datetime	No	ISO 8601 timestamp (read-only)

Query Parameters (List)

Field	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 20, max: 100)
q	string	No	Search by customer name or email

Example

List customers with pagination

bash

curl "https://api.mercozy.com/api/v1/external/customers?page=1&limit=20" \
  -H "X-API-Key: mk_live_xxxxx"

Create a customer

bash

curl -X POST "https://api.mercozy.com/api/v1/external/customers" \
  -H "X-API-Key: mk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890"
  }'

Example Response

json

{
  "data": {
    "id": "cust_abc123",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "createdAt": "2025-12-15T10:30:00Z",
    "updatedAt": "2025-12-15T10:30:00Z"
  }
}