Pagination & Filtering

Most list endpoints return paginated results. Use query parameters to control the page size and navigate through results.

---

Pagination Parameters

Parameter	Type	Default	Max	Description
page	integer	1	—	Page number (1-indexed)
per_page	integer	Depends on endpoint	100	Results per page

Default page sizes:

Endpoint	Default per_page
GET /api/v1/products	25
GET /api/v1/customers	25
GET /api/v1/sales	50
GET /api/v1/purchase_orders	50
GET /api/v1/stock_adjustments	100

These list endpoints are not paginated and return their full result in one response: categories, brands, loyalty tiers, loyalty rewards (both capped at 500), and webhook subscriptions.

Example

curl -H "X-API-Key: bpos_..." \
     "https://yourstore.brotherpos.ca/api/v1/products?page=2&per_page=50"

Pagination Response

Every paginated response includes a pagination object:

{
  "data": [ ... ],
  "pagination": {
    "current_page": 2,
    "per_page": 50,
    "total_count": 342,
    "total_pages": 7
  }
}

---

Filtering

Search

Endpoint	Parameter	Searches
Products	search	Name, SKU, barcode, weight-preset barcodes
Customers	q	Name, email, phone, customer code, loyalty card number
Sales	search	Sale ID, receipt number, customer name, email, phone

Product search does not match additional_barcodes. For customers, a query containing 7 or more digits is also matched against phone numbers with formatting stripped, so (306) 555-1234 finds 3065551234.

# Search products by name
curl -H "X-API-Key: bpos_..." \
     "https://yourstore.brotherpos.ca/api/v1/products?search=blue+dream"

# Search customers
curl -H "X-API-Key: bpos_..." \
     "https://yourstore.brotherpos.ca/api/v1/customers?q=john"

Category Filtering

Filter products by category slug:

curl -H "X-API-Key: bpos_..." \
     "https://yourstore.brotherpos.ca/api/v1/products?category=edibles"

Brand Filtering

Filter products by exact brand name:

curl -H "X-API-Key: bpos_..." \
     "https://yourstore.brotherpos.ca/api/v1/products?brand=Broken+Coast"

Unknown brands are ignored

If no brand has exactly that name, the filter is dropped and all products are returned — not an empty list.

Date Filtering

Filter sales by date range. Both start_date and end_date must be sent; if either is missing or unparseable, only today's sales are returned.

curl -H "X-API-Key: bpos_..." \
     "https://yourstore.brotherpos.ca/api/v1/sales?start_date=2026-03-01&end_date=2026-03-23"

end_date is effectively exclusive

Dates are compared as midnight, so sales during the end_date day itself are not included. To include March 22, send end_date=2026-03-23.

See Sales for the other sales filters.

Incremental Sync

Products and customers support updated_since for incremental syncing; purchase orders support it too.

# Only get products updated since 11:00 UTC
curl -H "X-API-Key: bpos_..." \
     "https://yourstore.brotherpos.ca/api/v1/products?updated_since=2026-03-22T11:00:00Z"

On products and customers, a value that cannot be parsed is ignored and the full list is returned. Purchase orders return 422 instead. The stock adjustment ledger uses since / until. See Recommended Sync Architecture.

---

What's Next?

• Error Handling — Understand error responses
• Webhooks — Event notifications
• Endpoints — Full endpoint reference