Pagination

Outbound endpoints return their results one page at a time. Use this page to control the page size and to fetch every page of a result.

How it works

Each GET that returns a list accepts two query parameters:

Parameter	Meaning
`Size`	The number of records per page: a whole number from `1` to `1000`. Default `100`.
`Cursor`	Where the page starts. Omit it for the first page; afterwards pass the `NextCursor` from the previous response.

The response holds the records in Data and the paging details in Paging:

Field	Meaning
`Paging.NextCursor`	The cursor for the next page, or `null` on the last page.
`Paging.CurrentDataCount`	The number of records in `Data` on this page.

Fetch every page

Request the first page without a Cursor:

GET /api/v1/locations?Size=2 HTTP/1.1
Host: acme.gainsystems.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqTl9F...

{
  "DataType": "location",
  "Data": [
    {
      "LocationCode": "CHI01",
      "Name": "Chicago Distribution Center",
      "Type": "DC",
      "ParentDefaultCode": null,
      "Address1": "2200 W Lake St",
      "Address2": null,
      "City": "Chicago",
      "State": "IL",
      "Country": "US",
      "PostalCode": "60612",
      "Latitude": 41.8847,
      "Longitude": -87.6808,
      "StartDate": "2024-01-01",
      "EndDate": null,
      "Size": "LARGE",
      "CurrencyCode": "USD"
    },
    {
      "LocationCode": "DAL02",
      "Name": "Dallas Branch",
      "Type": "Branch",
      "ParentDefaultCode": "CHI01",
      "Address1": "1500 Market Center Blvd",
      "Address2": null,
      "City": "Dallas",
      "State": "TX",
      "Country": "US",
      "PostalCode": "75207",
      "Latitude": 32.7957,
      "Longitude": -96.8217,
      "StartDate": "2025-03-15",
      "EndDate": null,
      "Size": "MEDIUM",
      "CurrencyCode": "USD"
    }
  ],
  "Paging": {
    "NextCursor": "k3Jf9QzX2mPa7LwT0bYc4g==",
    "CurrentDataCount": 2
  }
}

Then pass NextCursor as Cursor, with the same filters, and repeat until NextCursor is null:

GET /api/v1/locations?Size=2&Cursor=k3Jf9QzX2mPa7LwT0bYc4g%3D%3D HTTP/1.1
Host: acme.gainsystems.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJqTl9F...

Rules

Treat NextCursor as opaque. Pass it back exactly as received, URL-encoded like any query value; it can end in =.
Keep the same filters on every page. A cursor marks a position in one result; combining it with different filters gives an undefined result.
The last page can be full. Stop when NextCursor is null, not when a page holds fewer than Size records.
A cursor does not expire, but data that changes in GAINS while you page can appear on a later page or be missed.

What a record is

Size counts the units an endpoint returns:

Endpoints	One record is
Purchase, transfer, work and production orders	An order, with all its lines
Forecasts, inventory policies, service levels, bills of material, lead-time predictions	A SKU-location
All other list endpoints	One entry in `Data`

Errors

Status	`Reason`	Cause
`400`	`The page size parameter specified is not valid`	`Size` is not a whole number from 1 to 1000.
`400`	`Wrong cursor value`	`Cursor` was altered, truncated or not URL-encoded.

See Errors Handling & Exceptions for the error body.

How it works

Fetch every page

Rules

What a record is

Errors

Related