Customers API

Manage customer profiles for your merchant account. Create new customers, update existing ones, and retrieve customer lists with filtering options.

GET/public/api/v1/customers

customer:read

List all customers for the authenticated merchant account.

Example Request

curl -X GET \
  -H "Authorization: Bearer sntr_abcdefghijklmnopqrstuvwxyz123456" \
  https://sandbox.sentrypos.app/public/api/v1/customers

Example Response

{
  "customers": [
    {
      "id": "cmm3zkkx000006ogg8arp52qb",
      "name": "John Doe",
      "phone": "2025550123",
      "email": "john@example.com",
      "createdAt": "2026-02-26T15:30:00Z",
      "updatedAt": "2026-02-26T15:30:00Z"
    },
    {
      "id": "cmm3zkkx000006ogg8arp52qc",
      "name": "Jane Smith",
      "phone": "2025550124",
      "email": "jane@example.com",
      "createdAt": "2026-02-25T10:15:00Z",
      "updatedAt": "2026-02-26T09:45:00Z"
    }
  ]
}

POST/public/api/v1/customers

customer:write

Create a new customer or update an existing one by phone number.

Request Body

{
  "name": "John Doe",
  "phone": "2025550123",
  "email": "john@example.com"  // optional
}

Example Request

curl -X POST \
  -H "Authorization: Bearer sntr_abcdefghijklmnopqrstuvwxyz123456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "phone": "2025550123",
    "email": "john@example.com"
  }' \
  https://sandbox.sentrypos.app/public/api/v1/customers

Example Response

{
  "customer": {
    "id": "cmm3zkkx000006ogg8arp52qb",
    "name": "John Doe",
    "phone": "2025550123",
    "email": "john@example.com",
    "createdAt": "2026-02-26T15:30:00Z",
    "updatedAt": "2026-02-26T15:30:00Z"
  }
}

Customer Operations

The Customers API supports the following operations on individual customer records:

Endpoint	Method	Description	Scope
/customers/{id}	GET	Retrieve a specific customer by ID	customer:read
/customers/{id}	PUT	Update a customer by ID	customer:write

Data Model

Customer records have the following fields:

Field	Type	Required	Description
id	string	Auto	Unique customer identifier (CUID)
name	string	Yes	Customer's full name
phone	string	Yes	Phone number (unique per merchant)
email	string	No	Email address (optional)
createdAt	datetime	Auto	When the customer was created
updatedAt	datetime	Auto	When the customer was last updated

Error Handling

The Customers API returns standard HTTP status codes for error conditions:

Status	Error Code	Description
400	VALIDATION_ERROR	Invalid request data (missing name, invalid phone, etc.)
404	NOT_FOUND	Customer not found (for GET/PUT by ID)
409	CONFLICT	Phone number already exists for another customer

Integration Examples

OpenClaw Skill

An AI agent creating a customer before sending an invoice:

// 1. Create or update customer
POST /customers
{
  "name": "Alex Johnson",
  "phone": "2025550199",
  "email": "alex@example.com"
}

// 2. Use customer ID for invoice
POST /invoices
{
  "customerId": "cmm3zkkx000006ogg8arp52qb",
  "amountCents": 2500,
  "description": "Consulting services"
}

Website Checkout

E-commerce site creating customer during checkout:

// Upsert customer by phone
POST /customers
{
  "name": "Customer Name",
  "phone": "2025550123",
  "email": "customer@example.com"
}

// Response includes customer ID
// Use for invoice creation and payment

Next: Invoices API

Now that you can manage customers, learn how to create and send invoices using the Invoices API.

Go to Invoices API