← API Documentation

Customers API

Manage customers in your store. Customers represent people who have made purchases or been added to your customer database.

Endpoints

List Customers - GET /api/v1/customers/
Create Customer - POST /api/v1/customers/
Get Customer - GET /api/v1/customers/{id}/
Update Customer - PUT /api/v1/customers/{id}/

List Customers

Retrieve a paginated list of customers for your store.

Endpoint: GET /api/v1/customers/

Permission Required: Read

Query Parameters

Parameter	Type	Description
`after`	string	Cursor for pagination. Customer ID to return customers after (e.g., `cus_d0b6fmv28q6vn14peun0`)
`email`	string	Filter by customer email address
`search`	string	Search customers by name or email

Request

curl -X GET "https://studio.easel.engineering/api/v1/customers/?search=john&after=cus_d0b6fmv28q6vn14peun0" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "cus_d0b6fmv28q6vn14peun0",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:15:00Z"
    },
    {
      "id": "cus_xk3mq7r41p8nt26zv9w0",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "phone": null,
      "created_at": "2023-01-02T09:00:00Z",
      "updated_at": "2023-01-02T09:00:00Z"
    }
  ],
  "has_more": true
}

Error Responses

Invalid cursor parameter

Status: 400 Bad Request

{
  "error": "Invalid 'after' parameter",
  "code": "INVALID_FIELD"
}

Failed to list customers

Status: 500 Internal Server Error

{
  "error": "Failed to list customers",
  "code": "LIST_ERROR"
}

Create Customer

Create a new customer in your store.

Endpoint: POST /api/v1/customers/

Permission Required: Write

Request Body

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890"
}

Fields

Field	Type	Required	Description
`first_name`	string	Yes	Customer's first name
`last_name`	string	Yes	Customer's last name
`email`	string	Yes	Customer's email address
`phone`	string	No	Customer's phone number

Request

curl -X POST "https://studio.easel.engineering/api/v1/customers/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890"
  }'

Optional Headers:

Idempotency-Key: Unique string to prevent duplicate customer creation (see Idempotency)

Response

Returns the created customer.

Status: 201 Created

{
  "id": "cus_d0b6fmv28q6vn14peun0",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:00:00Z"
}

Error Responses

Invalid JSON body

Status: 400 Bad Request

{
  "error": "Invalid JSON body",
  "code": "INVALID_JSON"
}

Missing required field

Status: 400 Bad Request

{
  "error": "First name is required",
  "code": "MISSING_FIELD"
}

Failed to create customer

Status: 500 Internal Server Error

{
  "error": "Failed to create customer",
  "code": "CREATE_ERROR"
}

Customer created but failed to retrieve

Status: 500 Internal Server Error

{
  "error": "Customer created but failed to retrieve",
  "code": "GET_ERROR"
}

Get Customer

Retrieve a single customer by their public ID.

Endpoint: GET /api/v1/customers/{id}/

Permission Required: Read

Path Parameters

Parameter	Type	Description
`id`	string	Customer public ID (e.g., `cus_d0b6fmv28q6vn14peun0`)

Request

curl -X GET "https://studio.easel.engineering/api/v1/customers/cus_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "id": "cus_d0b6fmv28q6vn14peun0",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1234567890",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:15:00Z"
}

Error Responses

Missing customer ID

Status: 400 Bad Request

{
  "error": "Customer ID is required",
  "code": "MISSING_FIELD"
}

Customer not found

Status: 404 Not Found

{
  "error": "Customer not found",
  "code": "NOT_FOUND"
}

Failed to get customer

Status: 500 Internal Server Error

{
  "error": "Failed to get customer",
  "code": "GET_ERROR"
}

Update Customer

Update an existing customer's information.

Endpoint: PUT /api/v1/customers/{id}/

Permission Required: Write

Path Parameters

Parameter	Type	Description
`id`	string	Customer public ID (e.g., `cus_d0b6fmv28q6vn14peun0`)

Request Body

{
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com",
  "phone": "+1987654321"
}

Fields

Field	Type	Required	Description
`first_name`	string	Yes	Customer's first name
`last_name`	string	Yes	Customer's last name
`email`	string	Yes	Customer's email address
`phone`	string	No	Customer's phone number

Request

curl -X PUT "https://studio.easel.engineering/api/v1/customers/cus_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-67890" \
  -d '{
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "phone": "+1987654321"
  }'

Optional Headers:

Idempotency-Key: Unique string to prevent duplicate customer updates (see Idempotency)

Response

Returns the updated customer.

Status: 200 OK

{
  "id": "cus_d0b6fmv28q6vn14peun0",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com",
  "phone": "+1987654321",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T11:30:00Z"
}

Error Responses

Missing customer ID

Status: 400 Bad Request

{
  "error": "Customer ID is required",
  "code": "MISSING_FIELD"
}

Invalid JSON body

Status: 400 Bad Request

{
  "error": "Invalid JSON body",
  "code": "INVALID_JSON"
}

Missing required field

Status: 400 Bad Request

{
  "error": "First name is required",
  "code": "MISSING_FIELD"
}

Customer not found

Status: 404 Not Found

{
  "error": "Customer not found",
  "code": "NOT_FOUND"
}

Failed to update customer

Status: 500 Internal Server Error

{
  "error": "Failed to update customer",
  "code": "UPDATE_ERROR"
}

Customer updated but failed to retrieve

Status: 500 Internal Server Error

{
  "error": "Customer updated but failed to retrieve",
  "code": "GET_ERROR"
}

Customer Object

Fields

Field	Type	Description
`id`	string	Customer public ID
`first_name`	string	Customer's first name
`last_name`	string	Customer's last name
`email`	string	Customer's email address
`phone`	string\|null	Customer's phone number
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Phone Numbers

Phone numbers are stored as provided by the client
No specific format is enforced, but E.164 format is recommended (e.g., +1234567890)
Phone numbers can be null if not provided