Pagination

Large result sets are paginated to improve performance and manageability. Use pageStartIndex and pageSize parameters to control data retrieval.

How it works

Use these query parameters:

• pageStartIndex: 1‑based index of the first item
• pageSize: number of items per page

When pagination is active, the API returns an X-Pagination header with:

• TotalCount
• TotalPages
• PrevPageLink
• NextPageLink

Use case: Sync a full catalog without timeouts.

Example: page through products

const baseUrl = 'https://api.hlc.bike/us/v3.0'
const apiKey = process.env.HLC_API_KEY

async function* paginate(path, pageSize = 200) {
  let pageStartIndex = 1

  while (true) {
    const url = `${baseUrl}${path}?pageStartIndex=${pageStartIndex}&pageSize=${pageSize}`
    const res = await fetch(url, { headers: { ApiKey: apiKey } })

    if (!res.ok) throw new Error(`Page ${pageStartIndex} failed`)
    const data = await res.json()

    yield data

    const header = res.headers.get('x-pagination')
    const meta = header ? JSON.parse(header) : {}
    if (!meta.NextPageLink) break

    pageStartIndex += pageSize
  }
}