> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jethings.com/llms.txt
> Use this file to discover all available pages before exploring further.
# POS API
> Point of Sale API for retrieving and managing products
# POS API
The POS (Point of Sale) API provides endpoints for retrieving products in a store's inventory. This API is designed for point-of-sale systems to quickly search and access product information.
All POS API endpoints require the `x-store-id` header to identify which store's products you want to access.
## Endpoint Details
**Base URL:** `http://localhost:3000`\
**Content-Type:** `application/json`
### Required Headers
```
x-store-id:
Authorization: Bearer
```
The `x-store-id` header is required for all POS endpoints. Requests without this header will be rejected.
***
## Get Products
GET `/pos/products`
Retrieve a paginated list of products from a store's inventory. Each product includes all available prices across price lists. Supports search functionality to filter products.
**Requires Authentication:** Bearer token in Authorization header\
**Requires Header:** `x-store-id`
### Query Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------------------------------------------- |
| `search` | string | No | Search term to filter products (e.g., by barcode, name, or product reference) |
### Success Response
**Status Code:** `200 OK`
```json theme={null}
{
"data": [
{
"name": "jjjj",
"image": "https://abdellah.b-cdn.net/products/items/tzis6p7gi3f5q91xtct0u4au/1761827324350_Mens_FW25_CasualSneakers.jpg",
"quantity": 49,
"prices": [],
"createdAt": "2025-10-30T12:28:41.747Z",
"updatedAt": "2025-10-30T12:28:41.747Z",
"id": "nrabg76ezxvwnd749r7etafd"
},
{
"name": "jjjj",
"image": "https://abdellah.b-cdn.net/products/items/hgmc3gar2nsiecfsgtpjutvt/1761827322049_H0t0sJZopuiOsQtqp4euPrdkBZvTg4r21135F720.jpg",
"quantity": 49,
"prices": [],
"createdAt": "2025-10-30T12:28:41.747Z",
"updatedAt": "2025-10-30T12:28:41.747Z",
"id": "wh8zubjozc9ekx78yduntv4w"
},
{
"name": "Midnight Black",
"image": "https://abdellah.b-cdn.net/products/items/j92cmqkko4ljoe2ha8nwde9f/1762004747826_Mens_FW25_CasualSneakers.jpg",
"quantity": 10,
"prices": [
{
"priceListId": "crvd4jeb31gznu4qzs4t1k8a",
"priceListName": "abdellah price",
"price": 12500
}
],
"createdAt": "2025-11-01T13:45:43.879Z",
"updatedAt": "2025-11-01T13:45:43.879Z",
"id": "bm4r529seyhh21446upri0m2"
},
{
"name": "Stone Grey",
"image": "https://abdellah.b-cdn.net/products/items/bht3aspmzo2cg3kkhxzirf99/1762004745945_H0t0sJZopuiOsQtqp4euPrdkBZvTg4r21135F720.jpg",
"quantity": 8,
"prices": [
{
"priceListId": "crvd4jeb31gznu4qzs4t1k8a",
"priceListName": "abdellah price",
"price": 10800
}
],
"createdAt": "2025-11-01T13:45:43.879Z",
"updatedAt": "2025-11-01T13:45:43.879Z",
"id": "k6kcxaoyjf0poqv4vv9tgiwe"
},
{
"name": "Nike one",
"image": "https://abdellah.b-cdn.net/products/items/h9twtvzikih4mrqng29apcyw/1761832047401_H0t0sJZopuiOsQtqp4euPrdkBZvTg4r21135F720.jpg",
"quantity": 55,
"prices": [],
"createdAt": "2025-10-30T13:47:26.896Z",
"updatedAt": "2025-10-30T13:47:26.896Z",
"id": "t191h7axvurl5k0t17m63n3d"
},
{
"name": "Sand Beige",
"image": "https://abdellah.b-cdn.net/products/items/fp471iit18jprgbtxsdj8shx/1762004752375_H0t0sJZopuiOsQtqp4euPrdkBZvTg4r21135F720.jpg",
"quantity": 7,
"prices": [
{
"priceListId": "crvd4jeb31gznu4qzs4t1k8a",
"priceListName": "abdellah price",
"price": 11000
}
],
"createdAt": "2025-11-01T13:45:43.879Z",
"updatedAt": "2025-11-01T13:45:43.879Z",
"id": "k03rz7w1wp9xy3ztkb3d7vkn"
},
{
"name": "Sky Fade",
"image": "https://abdellah.b-cdn.net/products/items/iw05v14ismfow4dqnyw8hkqn/1762004753778_Mens_FW25_CasualSneakers.jpg",
"quantity": 11,
"prices": [
{
"priceListId": "crvd4jeb31gznu4qzs4t1k8a",
"priceListName": "abdellah price",
"price": 11300
}
],
"createdAt": "2025-11-01T13:45:43.879Z",
"updatedAt": "2025-11-01T13:45:43.879Z",
"id": "pl6pl3dlwzbzrqpb1okkyksy"
},
{
"name": "Ash White",
"image": "https://abdellah.b-cdn.net/products/items/xsj3wnt41e6ddjb8ox4x2w6q/1762004757040_Mens_FW25_CasualSneakers.jpg",
"quantity": 10,
"prices": [
{
"priceListId": "crvd4jeb31gznu4qzs4t1k8a",
"priceListName": "abdellah price",
"price": 10500
}
],
"createdAt": "2025-11-01T13:45:43.879Z",
"updatedAt": "2025-11-01T13:45:43.879Z",
"id": "kr3uxgc4hbmm528f77twjhmr"
},
{
"name": "Nike two",
"image": "https://abdellah.b-cdn.net/products/items/jmyr6vxi30rc8aqiu3gn7s6e/1762163947336_Mens_FW25_CasualSneakers.jpg",
"quantity": 6,
"prices": [],
"createdAt": "2025-11-03T09:59:07.246Z",
"updatedAt": "2025-11-03T09:59:07.246Z",
"id": "xg6gn50a1n1bmzyvb77eg0w0"
},
{
"name": "Nike two",
"image": "https://abdellahpull.b-cdn.net/products/items/r6luqkcanybgiprjoj0yinf7/1762600773063_Mens_FW25_CasualSneakers.jpg",
"quantity": 6,
"prices": [],
"createdAt": "2025-11-08T11:19:33.009Z",
"updatedAt": "2025-11-08T11:19:33.009Z",
"id": "yljahguowdl26qpddp740nv7"
},
{
"name": "Charcoal Fade",
"image": "https://abdellah.b-cdn.net/products/items/zsc280n4ihr1x2ra8u500si1/1762004755335_H0t0sJZopuiOsQtqp4euPrdkBZvTg4r21135F720.jpg",
"quantity": 5,
"prices": [
{
"priceListId": "crvd4jeb31gznu4qzs4t1k8a",
"priceListName": "abdellah price",
"price": 11800
}
],
"createdAt": "2025-11-01T13:45:43.879Z",
"updatedAt": "2025-11-01T13:45:43.879Z",
"id": "cdtwhvark9qnagmrn8fob3zd"
},
{
"name": "Washed Blue",
"image": "https://abdellah.b-cdn.net/products/items/r8fylfw9qwg59fq64lfx40m3/1762004743580_Mens_FW25_CasualSneakers.jpg",
"quantity": 12,
"prices": [
{
"priceListId": "crvd4jeb31gznu4qzs4t1k8a",
"priceListName": "abdellah price",
"price": 11500
}
],
"createdAt": "2025-11-01T13:45:43.879Z",
"updatedAt": "2025-11-01T13:45:43.879Z",
"id": "hlt1pgg3jpottpr3r6s0pbqi"
},
{
"name": "Vintage Blue",
"image": "https://abdellah.b-cdn.net/products/items/s66xncip0of44736bb1ssfm4/1762004749318_H0t0sJZopuiOsQtqp4euPrdkBZvTg4r21135F720.jpg",
"quantity": 6,
"prices": [
{
"priceListId": "crvd4jeb31gznu4qzs4t1k8a",
"priceListName": "abdellah price",
"price": 11200
}
],
"createdAt": "2025-11-01T13:45:43.879Z",
"updatedAt": "2025-11-01T13:45:43.879Z",
"id": "ux7vq7zm4n5b4oa8sfccac48"
},
{
"name": "jjjj",
"image": "https://abdellah.b-cdn.net/products/items/nc0kzztvw8k0navwc6i3juuk/1761828362970_H0t0sJZopuiOsQtqp4euPrdkBZvTg4r21135F720.jpg",
"quantity": 49,
"prices": [],
"createdAt": "2025-10-30T12:46:02.628Z",
"updatedAt": "2025-10-30T12:46:02.628Z",
"id": "cukh3liez2g9mzsk5ucqgyl3"
},
{
"name": "Nike two",
"image": "https://abdellahpull.b-cdn.net/products/items/jf3imx5iwriknlzdbe7hyklg/1762600693381_Screenshot 2025-11-05 at 11.48.56 PM.png",
"quantity": 6,
"prices": [],
"createdAt": "2025-11-08T11:18:13.284Z",
"updatedAt": "2025-11-08T11:18:13.284Z",
"id": "bjrf27vdot5hlmj98l5wzf7d"
},
{
"name": "Rust Brown",
"image": "https://abdellah.b-cdn.net/products/items/l025vivwu1qsnsh4nosset8q/1762004758368_H0t0sJZopuiOsQtqp4euPrdkBZvTg4r21135F720.jpg",
"quantity": 8,
"prices": [
{
"priceListId": "crvd4jeb31gznu4qzs4t1k8a",
"priceListName": "abdellah price",
"price": 12300
}
],
"createdAt": "2025-11-01T13:45:43.879Z",
"updatedAt": "2025-11-01T13:45:43.879Z",
"id": "n86arg7d9t8ud3qth6mv2g20"
},
{
"name": "Olive Green",
"image": "https://abdellah.b-cdn.net/products/items/irasckwdvmac4f7suatqhvox/1762004750820_Mens_FW25_CasualSneakers.jpg",
"quantity": 9,
"prices": [
{
"priceListId": "crvd4jeb31gznu4qzs4t1k8a",
"priceListName": "abdellah price",
"price": 12000
}
],
"createdAt": "2025-11-01T13:45:43.879Z",
"updatedAt": "2025-11-01T13:45:43.879Z",
"id": "f8u4ywluv3fq7czyno2dv9fc"
},
{
"name": "Nike two",
"image": "",
"quantity": 6,
"prices": [],
"createdAt": "2025-11-03T09:58:09.549Z",
"updatedAt": "2025-11-03T09:58:09.549Z",
"id": "mwz2aqg2a1xhsj4h45ehleb4"
}
],
"pagination": {
"page": 1,
"limit": 10,
"total": 18,
"totalPages": 2,
"hasNext": true,
"hasPrev": false
}
}
```
### Response Fields
#### Product Object
| Field | Type | Description |
| ----------- | ----------------- | -------------------------------------------------------- |
| `id` | string | Unique product identifier |
| `name` | string \| null | Product name (can be null) |
| `image` | string | URL to the product image |
| `quantity` | number | Available quantity in stock |
| `prices` | array | List of price entries for the product across price lists |
| `createdAt` | string (ISO 8601) | Product creation timestamp |
| `updatedAt` | string (ISO 8601) | Last update timestamp |
#### Price Object (within `prices`)
| Field | Type | Description |
| --------------- | ------ | ---------------------------------------------------- |
| `priceListId` | string | Price list identifier |
| `priceListName` | string | Human-readable price list name |
| `price` | number | Price value for this product in the given price list |
#### Pagination Object
| Field | Type | Description |
| ------------ | ------- | -------------------------------- |
| `page` | number | Current page number |
| `limit` | number | Number of items per page |
| `total` | number | Total number of items |
| `totalPages` | number | Total number of pages |
| `hasNext` | boolean | Whether there is a next page |
| `hasPrev` | boolean | Whether there is a previous page |
### Possible Errors
* `400 Bad Request`: Invalid query parameters or missing required headers
* `401 Unauthorized`: Missing or invalid authentication token
* `403 Forbidden`: Insufficient permissions or invalid store access
* `404 Not Found`: Store not found
### Example Requests
**Get all products:**
```bash theme={null}
curl -X GET "http://localhost:3000/pos/products" \
-H "x-store-id: YOUR_STORE_ID" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
**Search products by barcode:**
```bash theme={null}
curl -X GET "http://localhost:3000/pos/products?search=B001" \
-H "x-store-id: YOUR_STORE_ID" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
**Search products by name:**
```bash theme={null}
curl -X GET "http://localhost:3000/pos/products?search=Nike" \
-H "x-store-id: YOUR_STORE_ID" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```
***
## Business Logic
### Store Context
* All product queries are scoped to the store specified in the `x-store-id` header
* The store ID must be valid and the user must have access to that store
* Products from other stores are not accessible through this endpoint
### Pricing
* Each product includes all available price entries in the `prices` array
* A product may have zero or more price entries, depending on associated price lists
### Search Functionality
* The search parameter filters products across multiple fields (e.g., barcode, name, reference)
* Search is case-insensitive and supports partial matching
* If no search parameter is provided, all products in the store are returned (with pagination)
### Pagination
* Results are paginated by default
* Default page size is 10 items per page
* Use pagination metadata to navigate through results