Reference

Pagination

All list endpoints support offset-based pagination using skip and take parameters. Some endpoints also support incremental sync via updatedSince.

Skip / Take

Use skip and take query parameters to page through results.

Parameter	Type	Description
`skip`	number	Number of records to skip from the beginning (default: 0)
`take`	number	Number of records to return (default: 10, max: 50 on most endpoints)

First page

GET /v0/shipments?take=50&skip=0

Second page

GET /v0/shipments?take=50&skip=50

Third page

GET /v0/shipments?take=50&skip=100

Iterating All Records

To fetch all records, increment skip by your page size until you receive fewer results than requested:

Paginate all shipments (Node.js)

async function getAllShipments(token) {
  const pageSize = 50;
  let skip = 0;
  const all = [];

  while (true) {
    const res = await fetch(
      `https://api.3plguys.com/v0/shipments?take=${pageSize}&skip=${skip}`,
      { headers: { Authorization: `Bearer ${token}` } }
    );
    const page = await res.json();
    all.push(...page);

    if (page.length < pageSize) break; // Last page
    skip += pageSize;
  }

  return all;
}

Incremental Sync

Stock level endpoints support an updatedSince parameter for efficient delta syncing. Pass an ISO 8601 timestamp to only receive records that changed since your last sync.

Parameter	Type	Description
`updatedSince`	ISO 8601	Only return records updated after this timestamp

Incremental stock sync

GET /v0/inventory/products/breakdown?updatedSince=2026-03-04T00:00:00.000Z

Sync Pattern

Store the timestamp of your last sync, then pass it on the next request to only receive changes:

Delta sync pattern (Node.js)

let lastSync = null; // Store persistently (database, file, etc.)

async function syncStockLevels(token) {
  const url = new URL("https://api.3plguys.com/v0/inventory/products/breakdown");
  if (lastSync) url.searchParams.set("updatedSince", lastSync);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${token}` },
  });
  const updates = await res.json();

  // Process updates (upsert into your local database)
  for (const item of updates) {
    await upsertLocalStock(item);
  }

  // Save current time for next sync
  lastSync = new Date().toISOString();
  return updates;
}

Filtering & Sorting

Most list endpoints support filtering and sorting alongside pagination:

Endpoint	Filters	Sort
`/v0/shipments`	status, type	createdAt desc (default)
`/v0/inventory/products`	search, sku, includeDeleted	sortBy, sortOrder
`/v0/inventory/cartons`	search, productId, includeDeleted	sortBy, sortOrder
`/v0/notifications`	type, severity	createdAt desc (default)
`/v0/invoices`	status, search	sortBy, sortOrder

Combined example

GET /v0/shipments?type=outbound-spd&status=pending&take=20&skip=0

Pagination tips

Always handle the case where a page returns fewer results than take — this indicates the last page.
Don't assume a fixed total count. Iterate until a short page.
For large datasets, prefer incremental sync with updatedSince over full re-fetches.
The maximum take value is 50 on most endpoints. Exceeding it returns a 400 error.

Error Handling

Changelog