Customers and stock API
Paid plansList, 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=25Customers come oldest first.
Filters:
| Parameter | Values |
|---|---|
q | The start of the e-mail, last or first name, company or phone, 2 characters or more |
email | An exact e-mail address |
status | active, blocked or erased |
customer_group_id | A customer group (cgr_...) |
tag | A 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_.../addressesPOST /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/locationsLists 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=100One 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_inorimport.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.
Related
Updated 13 November 2026