Customers API

Manage customer data for the authenticated store. Customers are users who have placed orders or created accounts on the storefront.

List Customers

Retrieve a paginated list of customers with order summary data.

GET /api/apps/v1/customers

Authentication

Required. Must include valid app credentials.

Scope

read:customers

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`50`	Items per page (max 250)
`sort`	string	`created_at:desc`	Sort results. Format: `column:asc` or `column:desc`. Allowed: `created_at`, `updated_at`, `name`
`since`	string (ISO 8601)	--	Only return customers created on or after this date
`search`	string	--	Search by name, email, or phone
`include_guests`	string	`false`	Set to `true` to include guest checkout customers
`total_orders_min`	integer	--	Only return customers with at least this many orders
`total_spent_min`	integer	--	Only return customers who have spent at least this amount

Example Request

curl -X GET "https://api.selorax.io/api/apps/v1/customers?page=1&limit=50&sort=created_at:desc" \
  -H "Authorization: Bearer <token>"

Search for customers and filter by spend:

curl -X GET "https://api.selorax.io/api/apps/v1/customers?search=rahim&total_spent_min=5000" \
  -H "Authorization: Bearer <token>"

Or using client credentials:

curl -X GET "https://api.selorax.io/api/apps/v1/customers?since=2025-06-01T00:00:00Z&limit=50" \
  -H "X-Client-Id: sx_app_..." \
  -H "X-Client-Secret: sx_secret_..." \
  -H "X-Store-Id: 22"

Response

{
  "data": [
    {
      "user_id": 301,
      "store_id": 22,
      "name": "Rahim Ahmed",
      "email": "[email protected]",
      "phone": "01712345678",
      "address_json": {"address": "123 Main St", "city": "Dhaka"},
      "is_guest": 0,
      "created_at": "2025-01-20T06:30:00.000Z",
      "updated_at": "2025-06-15T10:30:00.000Z",
      "total_orders": 12,
      "total_spent": 18500
    },
    {
      "user_id": 289,
      "store_id": 22,
      "name": "Fatima Khatun",
      "email": null,
      "phone": "01898765432",
      "address_json": null,
      "is_guest": 0,
      "created_at": "2025-03-05T14:00:00.000Z",
      "updated_at": "2025-06-10T08:45:00.000Z",
      "total_orders": 3,
      "total_spent": 4200
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 2
  },
  "status": 200
}

Response Fields

Field	Type	Description
`user_id`	integer	Unique customer identifier
`store_id`	integer	Store the customer belongs to
`name`	string	Customer full name
`email`	string or null	Customer email address
`phone`	string	Customer phone number
`address_json`	object or null	Customer's saved address
`is_guest`	integer (0 or 1)	Whether the customer is a guest checkout user
`total_orders`	integer	Total number of orders placed
`total_spent`	integer	Total amount spent across all orders
`created_at`	string (ISO 8601)	When the customer account was created
`updated_at`	string (ISO 8601)	When the customer record was last updated

Node.js Example

const response = await fetch(
  "https://api.selorax.io/api/apps/v1/customers?search=rahim&sort=name:asc",
  { headers: { Authorization: "Bearer sx_at_..." } }
);
const { data, pagination } = await response.json();
console.log(`Found ${pagination.total} customers`);

Python Example

import requests
 
response = requests.get(
    "https://api.selorax.io/api/apps/v1/customers",
    headers={"Authorization": "Bearer sx_at_..."},
    params={"total_orders_min": 5, "sort": "created_at:desc", "limit": 50},
)
data = response.json()
for customer in data["data"]:
    print(f"{customer['name']}: {customer['total_orders']} orders, ৳{customer['total_spent']}")

Get Customer

Retrieve a single customer by user ID, including order summary and verification status.

GET /api/apps/v1/customers/:user_id

Authentication

Required. Must include valid app credentials.

Scope

read:customers

Path Parameters

Parameter	Type	Description
`user_id`	integer	The customer's user ID

Example Request

curl -X GET "https://api.selorax.io/api/apps/v1/customers/301" \
  -H "Authorization: Bearer <token>"

Response

{
  "data": {
    "user_id": 301,
    "store_id": 22,
    "name": "Rahim Ahmed",
    "email": "[email protected]",
    "phone": "01712345678",
    "address_json": {"address": "123 Main St", "city": "Dhaka"},
    "is_guest": 0,
    "is_phone_verified": 1,
    "is_email_verified": 0,
    "created_at": "2025-01-20T06:30:00.000Z",
    "updated_at": "2025-06-15T10:30:00.000Z",
    "total_orders": 12,
    "total_spent": 18500
  },
  "status": 200
}

Response Fields

Includes all list fields plus:

Field	Type	Description
`is_phone_verified`	integer (0 or 1)	Whether the customer's phone is verified
`is_email_verified`	integer (0 or 1)	Whether the customer's email is verified

Error Responses

Code	Status	Meaning
`invalid_token`	401	Token is expired or invalid
`insufficient_scope`	403	App does not have `read:customers` scope

If the user_id does not exist or does not belong to the authenticated store:

{
  "message": "Customer not found.",
  "status": 404
}

Update Customer

Update a customer's information. Only provided fields are updated.

PUT /api/apps/v1/customers/:user_id

Authentication

Required. Must include valid app credentials.

Scope

write:customers

Path Parameters

Parameter	Type	Description
`user_id`	integer	The customer's user ID

Request Body

Field	Type	Required	Description
`name`	string	No	Customer full name (max 255 characters)
`email`	string	No	Valid email address
`phone`	string	No	Phone number (max 20 characters)
`address_json`	object	No	Customer address as a JSON object

At least one field must be provided.

Example Request

curl -X PUT "https://api.selorax.io/api/apps/v1/customers/301" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Rahim Ahmed Khan",
    "address_json": {
      "address": "456 New Street",
      "city": "Dhaka",
      "area": "Gulshan"
    }
  }'

Response

{
  "data": {
    "user_id": 301,
    "store_id": 22,
    "name": "Rahim Ahmed Khan",
    "email": "[email protected]",
    "phone": "01712345678",
    "address_json": {"address": "456 New Street", "city": "Dhaka", "area": "Gulshan"},
    "is_guest": 0,
    "is_phone_verified": 1,
    "is_email_verified": 0,
    "created_at": "2025-01-20T06:30:00.000Z",
    "updated_at": "2025-06-20T12:00:00.000Z"
  },
  "message": "Customer updated.",
  "status": 200
}

Error Responses

Code	Status	Meaning
`invalid_token`	401	Token is expired or invalid
`insufficient_scope`	403	App does not have `write:customers` scope
--	400	Validation error (invalid email, missing fields, etc.)
--	404	Customer not found

Customer Order History

Retrieve a paginated list of orders for a specific customer. This is a sub-resource to keep sensitive order data separate from the customer profile.

GET /api/apps/v1/customers/:user_id/orders

Authentication

Required. Must include valid app credentials.

Scope

read:customers

Path Parameters

Parameter	Type	Description
`user_id`	integer	The customer's user ID

Query Parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number
`limit`	integer	`50`	Items per page (max 250)
`status`	string	--	Filter by order status (e.g. `pending`, `confirmed`, `delivered`)

Example Request

curl -X GET "https://api.selorax.io/api/apps/v1/customers/301/orders?status=delivered&limit=10" \
  -H "Authorization: Bearer <token>"

Response

{
  "data": [
    {
      "order_id": 1045,
      "store_id": 22,
      "user_id": 301,
      "order_status": "delivered",
      "financial_status": "paid",
      "fulfillment_status": "fulfilled",
      "sub_total": 1500,
      "tax": 0,
      "shipping": 60,
      "discount": 100,
      "grand_total": 1460,
      "payment_method": "cod",
      "note": null,
      "created_at": "2025-06-15T10:30:00.000Z",
      "updated_at": "2025-06-18T14:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 1
  },
  "status": 200
}

Response Fields

Same fields as the Orders API list response.

Error Responses

Returns 404 if the customer does not exist or does not belong to the authenticated store.

Create Customer

Create a new customer. Phone number must be unique per store.

POST /api/apps/v1/customers

Scope

write:customers

Request Body

Field	Type	Required	Description
`name`	string	Yes	Customer name
`phone`	string	Yes	Phone number (min 10 characters, unique per store)
`email`	string	No	Email address
`address`	object	No	Address object (stored as JSON)

Example Request

curl -X POST "https://api.selorax.io/api/apps/v1/customers" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Karim Hossain",
    "phone": "01812345678",
    "email": "[email protected]",
    "address": {
      "address": "789 Park Avenue",
      "city": "Chittagong"
    }
  }'

Response (201)

{
  "data": {
    "user_id": 350,
    "name": "Karim Hossain",
    "phone": "01812345678",
    "email": "[email protected]",
    "store_id": 22
  },
  "status": 201
}

Error Responses

Status	Meaning
400	Missing name or phone
409	Phone number already exists for this store

Delete Customer

Delete a customer. Customers with existing orders cannot be deleted.

DELETE /api/apps/v1/customers/:user_id

Scope

write:customers

Error Responses

Status	Meaning
400	Customer has orders (cannot delete)
404	Customer not found