Customers API
Store balance is credit a customer spends in your shop. A balance call that succeeds twice moves the amount twice.
On this page
The customer object
| Field | Type | Notes |
|---|---|---|
id, shop_id | string | UUIDs |
email | string | The account email |
name | string | Left out when empty |
balance | number | Store balance in USD |
total_orders | integer | Orders placed by the account |
total_spent | number | USD spent by the account |
email_verified | boolean | Whether the customer confirmed the address |
is_active | boolean | Whether the account is active |
last_login | string | Left out when the customer never signed in |
created_at, updated_at | string | Timestamps |
Do not send search on the list. It is not supported and the request fails. Page through the list and match on email yourself.
How store balance works for a buyer is in Customers and store balance.
List customers
GET /customers
Lists the store accounts of your shop, newest first.
| Parameter | Type | In | Rules |
|---|---|---|---|
page | integer | query | From 1. Default 1 |
limit | integer | query | Default 20, maximum 100 |
curl -H "Authorization: Bearer YOUR_KEY" \ "https://api.shopl.io/api/v1/customers?page=1"
200 OK { "success": true, "data": { "customers": [ { "id": "2682b9a4-3c5d-4e6f-8a7b-9c0d1e2f3a4b", "shop_id": "3f2a9c1b-7d44-4e0a-9a3c-1f5b8e2d6c70", "email": "[email protected]", "balance": 12.5, "total_orders": 7, "total_spent": 84.3, "email_verified": true, "is_active": true, "created_at": "2026-05-02T14:20:00Z", "updated_at": "2026-06-28T18:05:11Z" } ], "total": 214, "page": 1, "limit": 20 } }
- A buyer who checked out as a guest has no store account and is not in this list.
Get a customer
GET /customers/:id
Returns one customer with the current store balance.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Customer id (UUID) |
curl -H "Authorization: Bearer YOUR_KEY" \ https://api.shopl.io/api/v1/customers/CUSTOMER_ID
200 OK { "success": true, "data": { "id": "2682b9a4-3c5d-4e6f-8a7b-9c0d1e2f3a4b", "shop_id": "3f2a9c1b-7d44-4e0a-9a3c-1f5b8e2d6c70", "email": "[email protected]", "balance": 12.5, "total_orders": 7, "total_spent": 84.3, "email_verified": true, "is_active": true, "created_at": "2026-05-02T14:20:00Z", "updated_at": "2026-06-28T18:05:11Z" } }
Add store balance
POST /customers/:id/balance/add
Credits a customer's store balance. The customer can spend it in your shop at once.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Customer id (UUID) |
amount required | number | body | Greater than 0, in USD |
description | string | body | Shown in the balance history. Cut to 240 bytes. Absent means "Balance credit via API" |
{ "amount": 5, "description": "Loyalty reward" }curl -X POST \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":5,"description":"Loyalty reward"}' \
https://api.shopl.io/api/v1/customers/CUSTOMER_ID/balance/add200 OK { "success": true, "data": { "customer": { "id": "2682b9a4-3c5d-4e6f-8a7b-9c0d1e2f3a4b", "email": "[email protected]", "balance": 17.5 }, "transaction": { "id": "c3d4e5f6-7a8b-4c9d-8e0f-1a2b3c4d5e6f", "customer_id": "2682b9a4-3c5d-4e6f-8a7b-9c0d1e2f3a4b", "shop_id": "3f2a9c1b-7d44-4e0a-9a3c-1f5b8e2d6c70", "amount": 5, "type": "credit", "description": "Loyalty reward", "created_at": "2026-06-29T10:00:00Z" } } }
- Not safe to repeat: every successful call adds the amount again. If a call times out, read the customer before sending it a second time.
- This creates store credit. Grant write_orders only to integrations you trust with money.
Subtract store balance
POST /customers/:id/balance/subtract
Debits a customer's store balance. The balance never goes below 0.
| Parameter | Type | In | Rules |
|---|---|---|---|
id required | string | path | Customer id (UUID) |
amount required | number | body | Greater than 0, in USD |
description | string | body | Shown in the balance history. Cut to 240 bytes. Absent means "Balance debit via API" |
{ "amount": 2.5, "description": "Manual adjustment" }curl -X POST \
-H "Authorization: Bearer YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"amount":2.5,"description":"Manual adjustment"}' \
https://api.shopl.io/api/v1/customers/CUSTOMER_ID/balance/subtract200 OK { "success": true, "data": { "customer": { "id": "2682b9a4-3c5d-4e6f-8a7b-9c0d1e2f3a4b", "email": "[email protected]", "balance": 15 }, "transaction": { "id": "d4e5f6a7-8b9c-4d0e-9f1a-2b3c4d5e6f7a", "customer_id": "2682b9a4-3c5d-4e6f-8a7b-9c0d1e2f3a4b", "shop_id": "3f2a9c1b-7d44-4e0a-9a3c-1f5b8e2d6c70", "amount": -2.5, "type": "debit", "description": "Manual adjustment", "created_at": "2026-06-29T10:05:00Z" } } }
- Not safe to repeat: every successful call subtracts the amount again.