Customers API

REST API endpoints for managing customers and their addresses.

List Customers

GET /api/v1/customers

Returns a paginated list of customers, sorted by creation date (newest first).

Query Parameters

Parameter	Type	Default	Description
`limit`	`number`	50	Customers per page (1-100)
`offset`	`number`	0	Customers to skip
`search`	`string`	–	Search by customer email

Response

{
  "items": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "email": "jane@example.com",
      "name": "Jane Doe",
      "locale": "en-US",
      "createdAt": "2024-01-10T08:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 156,
    "offset": 0,
    "limit": 50,
    "hasMore": true
  }
}

locale is the language the customer last shopped in (the storefront's language code, e.g. pl-PL), or null until they have bought or picked one on their account. Emails addressed to the customer render in it.

Get Customer

GET /api/v1/customers/:id

Returns customer details including linked user info and all saved addresses.

{
  "id": "0191abc0-1234-7def-8000-000000000001",
  "email": "jane@example.com",
  "name": "Jane Doe",
  "locale": "en-US",
  "phone": null,
  "addresses": [
    {
      "id": "0191abc0-0000-7000-8000-000000000010",
      "line1": "123 Main St",
      "line2": null,
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94102",
      "country": "US",
      "name": "Jane Doe",
      "company": null,
      "phone": null
    }
  ],
  "createdAt": "2024-01-10T08:00:00.000Z"
}

Update Customer

PATCH /api/v1/customers/:id

Request Body

Field	Type	Description
`name`	`string`	Customer display name
`phone`	`string`	Customer phone number

curl -X PATCH \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith"}' \
  https://your-store.yns.store/api/v1/customers/0191abc0-1234-7def-8000-000000000001

Customer Addresses

Create Address

POST /api/v1/customers/:id/addresses

Field	Type	Required	Description
`line1`	`string`	Yes	Street address line 1
`line2`	`string`	No	Apartment, suite, etc.
`city`	`string`	Yes	City
`postalCode`	`string`	Yes	Postal/ZIP code
`country`	`string`	No	Two-letter country code (e.g. `US`)
`state`	`string`	No	State or province
`name`	`string`	No	Recipient full name
`company`	`string`	No	Company name
`phone`	`string`	No	Contact phone number

curl -X POST \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "line1": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "postalCode": "90001",
    "country": "US",
    "name": "Jane Doe"
  }' \
  https://your-store.yns.store/api/v1/customers/0191abc0-1234-7def-8000-000000000001/addresses

Delete Address

DELETE /api/v1/customers/:id/addresses/:addressId

Removes an address from the customer's address book.

Customer Orders

GET /api/v1/customers/:id/orders

Returns orders placed by this customer, paginated. See Orders API for response details.

A request made for a person – through an OAuth app or the AI Assistant – lists only the orders that person's role may see; API keys list them all. See order visibility.

Query Parameters

Parameter	Type	Default	Description
`limit`	`number`	20	Orders per page (1-100)
`offset`	`number`	0	Orders to skip

Response

{
  "items": [
    {
      "id": "0191abc0-1234-7def-8000-000000000001",
      "orderNumber": "1042",
      "status": "completed",
      "totalCents": 5000,
      "currency": "usd",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "total": 8,
    "offset": 0,
    "limit": 20,
    "hasMore": false
  }
}

PreviousCartsAPI Reference NextCouponsAPI Reference