CartDocs

Customers and stock API

Paid plans

List, create and change customers and their addresses, read stock levels per variant or location, and adjust stock through the API.

On this page

These calls keep your customer records and your stock in step with other tools, such as a CRM, a till or a warehouse system. All examples leave out the Host: api.ixxocart.com and Authorization: Bearer ... headers, which every call needs. Every POST also needs an Idempotency-Key header (see Pagination, errors and limits).

Customers

List and find customers

GET /api/v1/customers?q=ioannou&limit=25

Customers come oldest first.

Filters:

ParameterValues
qThe start of the e-mail, last or first name, company or phone, 2 characters or more
emailAn exact e-mail address
statusactive, blocked or erased
customer_group_idA customer group (cgr_...)
tagA customer tag

Each customer has an id (cus_...), email, first_name, last_name, company, phone, language, currency, accepts_marketing, vat_number, customer_group, status, has_account, tags, created_at and updated_at. Needs See customers.

Read one customer

GET /api/v1/customers/cus_...

The answer adds an overview: the number of orders and subscriptions with the five newest of each, and the customer's membership.

Create a customer

POST /api/v1/customers
Content-Type: application/json
Idempotency-Key: 2f8a...

{
  "email": "maria@example.com",
  "first_name": "Maria",
  "last_name": "Ioannou",
  "phone": "+357 99 123456",
  "language": "el",
  "accepts_marketing": true,
  "marketing_wording": "Signed up at the shop counter for news and offers."
}

Only email is required. The customer gets a record without a login; they can register later with the same e-mail. An e-mail the shop already has gets 409 customers.email_taken. When you set accepts_marketing, add in marketing_wording what the customer agreed to: it is kept with the consent record. Needs Edit customers.

Change a customer

PATCH /api/v1/customers/cus_...
Content-Type: application/json

{ "phone": "+357 99 654321", "status": "blocked" }

Send only the fields you change. An erased customer cannot be changed.

Addresses

GET /api/v1/customers/cus_.../addresses
POST /api/v1/customers/cus_.../addresses
Content-Type: application/json
Idempotency-Key: 6d1e...

{
  "first_name": "Maria",
  "last_name": "Ioannou",
  "line1": "12 Makariou Avenue",
  "city": "Nicosia",
  "postcode": "1065",
  "country_code": "CY",
  "is_default_shipping": true
}

line1, city and country_code (two letters, such as CY or GR) are required. Change an address with PATCH /api/v1/customers/cus_.../addresses/adr_... and remove it with DELETE on the same path.

Stock

Stock is kept per variant (var_...) and per stock location (loc_...).

Stock locations

GET /api/v1/inventory/locations

Lists your stock locations and their IDs. Needs See stock levels and movements.

Stock levels

For one variant, in every location:

GET /api/v1/inventory/levels?variant_id=var_...

For every variant in one location, in pages:

GET /api/v1/inventory/levels?location_id=loc_...&limit=100

One of the two is required. Each level has the variant_id, location_id, on_hand (units in the location), reserved (units held for customers), available (on hand minus reserved) and updated_at.

To find a variant ID, read the product with include=variants (see Products API).

Adjust stock

Stock changes by a delta, not by setting a new total, so two tools can change the same stock without overwriting each other:

POST /api/v1/inventory/adjust
Content-Type: application/json
Idempotency-Key: a913...

{
  "variant_id": "var_...",
  "location_id": "loc_...",
  "delta": 12,
  "reason": "received",
  "note": "Delivery from supplier, invoice 4471"
}
  • delta: positive to add units, negative to take them away.
  • reason: received, adjustment, sale, return, transfer_out, transfer_in or import.
  • note: optional, kept with the movement.

The answer gives the variant's new levels. Units that customers hold cannot be taken away, unless the variant sells on backorder: such a call gets 409 insufficient_stock with what is available. Needs Adjust stock.

Stock history

GET /api/v1/inventory/movements?variant_id=var_...

Every stock change, newest first, with its reason. Filter by variant_id, location_id or reason.

Updated 13 November 2026