Pagination & Filtering

No pagination

The Shopwave API does not use traditional pagination (offset, cursor, or page-based). List endpoints return full result sets. Use header-based filtering to scope results to the records you need.

Filtering by ID

Most GET endpoints accept a comma-separated list of IDs as a request header to filter results. If the header is omitted, all records are returned.

curl

# Fetch only products 135592 and 135593
curl https://api.staging.merchantstack.com/product \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-accept-version: 2.0" \
  -H "productIds: 135592,135593"

JavaScript

const response = await fetch('https://api.staging.merchantstack.com/product', {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'x-accept-version': '2.0',
    'productIds': '135592,135593'
  }
})

const data = await response.json()
// data.products contains only the two requested products

Headers, not query strings

Filter parameters are passed as request headers, not query string parameters. This is different from most REST APIs — make sure your HTTP client sends these as headers.

Filter headers by resource

Each resource uses its own filter header name:

Endpoint	Filter header	Example
GET /application	applicationIds	1,2,4
GET /basket	basketIds	100,200
GET /category	categoryIds	1,2,3
GET /employee	employeeIds	1,2,4
GET /invoice	invoiceId	567,5678
GET /order	orderIds	1,2,4
GET /product	productIds	1,2,3
GET /promotion	promotionIds	1,2,4
GET /store	storeIds	1,2,3
GET /supplier/store	supplierIds	1,2,3

Cross-resource filtering

Some endpoints support filtering by related resources:

Endpoint	Header	Description
GET /product	storeId	Include stock levels for a specific store
GET /product	categoryIds	Filter products by category
GET /invoice	storeIds	Filter invoices by store
GET /order	storeIds	Filter orders by store
GET /order	completed	Filter by completion status (true/false)
GET /promotion	storeIds	Filter promotions by store
GET /promotion	active	Only active promotions (true/false)
GET /promotion	expired	Only expired promotions
GET /promotion	imminent	Promotions starting soon

Example: Products with stock for a store

curl

# Get products in category 921 with stock levels for store 2890
curl https://api.staging.merchantstack.com/product \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-accept-version: 2.0" \
  -H "categoryIds: 921" \
  -H "storeId: 2890"

JavaScript

const response = await fetch('https://api.staging.merchantstack.com/product', {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'x-accept-version': '2.0',
    'categoryIds': '921',
    'storeId': '2890'
  }
})

const { products } = await response.json()
// Each product includes totalStock, stockSold, stockLeft for store 2890

Response:

{
  "products": {
    "135592": {
      "id": 135592,
      "name": "Classic Beef Burger",
      "categories": { "921": "Mains" },
      "totalStock": 50,
      "stockSold": 12,
      "stockLeft": 38,
      "instances": { ... }
    }
  },
  "api": { ... }
}

Logs — tag-based filtering

The Log endpoint uses a different filtering model based on tags and object keys rather than IDs:

Header	Required	Description
tag	Yes	Custom tags to filter by (e.g. "StockTake, Product")
object	Yes	Object type key (e.g. "STORE")
identifier	Yes	Identifier value (e.g. "12")
id	No	Direct retrieval by composite log ID

Reports — date range filtering

Report endpoints use date range headers instead of ID filtering:

curl

# Get basket report for January 2024, store 53
curl https://api.staging.merchantstack.com/report/basket \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-accept-version: 2.0" \
  -H "reportFrom: 2024-01-01 00:00:00" \
  -H "reportTo: 2024-01-31 23:59:59" \
  -H "storeIds: 53"

JavaScript

const response = await fetch('https://api.staging.merchantstack.com/report/basket', {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'x-accept-version': '2.0',
    'reportFrom': '2024-01-01 00:00:00',
    'reportTo': '2024-01-31 23:59:59',
    'storeIds': '53'
  }
})

Stock reconciliation — date range filtering

The stock reconciliation endpoint also uses date ranges:

Header	Required	Description
from	Yes	Start date-time (e.g. 2024-01-01 00:00:00)
to	Yes	End date-time (e.g. 2024-06-01 00:00:00)
storeIds	Yes	Comma-separated store IDs

Best practices

• Filter aggressively — always pass ID filters when you know which records you need, rather than fetching everything
• Cache where possible — resources like categories, stores, and products change infrequently
• Use stock filtering — pass storeId when fetching products to get stock levels in a single request instead of a separate call