API · CustomersDocs navigation

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

FieldTypeNotes
id, shop_idstringUUIDs
emailstringThe account email
namestringLeft out when empty
balancenumberStore balance in USD
total_ordersintegerOrders placed by the account
total_spentnumberUSD spent by the account
email_verifiedbooleanWhether the customer confirmed the address
is_activebooleanWhether the account is active
last_loginstringLeft out when the customer never signed in
created_at, updated_atstringTimestamps

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

Scope read_orders

Lists the store accounts of your shop, newest first.

ParameterTypeInRules
pageintegerqueryFrom 1. Default 1
limitintegerqueryDefault 20, maximum 100
Request
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

Scope read_orders

Returns one customer with the current store balance.

ParameterTypeInRules
id requiredstringpathCustomer id (UUID)
Request
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"
  }
}
ErrorStatusWhen
Customer not found404No customer with that id in this shop.

Add store balance

POST /customers/:id/balance/add

Scope write_orders

Credits a customer's store balance. The customer can spend it in your shop at once.

ParameterTypeInRules
id requiredstringpathCustomer id (UUID)
amount requirednumberbodyGreater than 0, in USD
descriptionstringbodyShown in the balance history. Cut to 240 bytes. Absent means "Balance credit via API"
Request body
{ "amount": 5, "description": "Loyalty reward" }
Request
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/add
200 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.
ErrorStatusWhen
Customer not found404No customer with that id in this shop.
amount must be greater than 0400amount is missing, 0 or negative.

Subtract store balance

POST /customers/:id/balance/subtract

Scope write_orders

Debits a customer's store balance. The balance never goes below 0.

ParameterTypeInRules
id requiredstringpathCustomer id (UUID)
amount requirednumberbodyGreater than 0, in USD
descriptionstringbodyShown in the balance history. Cut to 240 bytes. Absent means "Balance debit via API"
Request body
{ "amount": 2.5, "description": "Manual adjustment" }
Request
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/subtract
200 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.
ErrorStatusWhen
Customer not found404No customer with that id in this shop.
amount must be greater than 0400amount is missing, 0 or negative.
Amount exceeds customer's current balance400The customer holds less than amount. Nothing is debited.

If the docs do not cover it, ask on Telegram or use the contact form.