Pagination
List queries (orders, repaymentRequests, paymentExternalTransactions, a brand's products, …) return connections: paginated lists that expose the items together with the metadata needed to walk the pages.
Two facts cover most needs:
- Pages hold at most 20 items: 20 is both the default and the maximum page size, so requesting
first: 50still returns 20. - To fetch the next page, pass the previous response's
pageInfo.endCursoras theafterargument, untilhasNextPageisfalse.
Connection fields
nodes: the items of the page. Use this unless you need per-item cursors.edges: the items wrapped with theircursor, useful to resume from a specific item.pageInfo:startCursor,endCursor,hasNextPage,hasPreviousPage.
Connections do not tell how many items match the query, so the number of pages is not known in advance: walk the pages until hasNextPage is false, and use a filter (for example on updatedAt, as the guides do) to keep them few.
Ordering
Items are returned in ascending id order (numeric, so 101 comes after 35), that is in the order OMS recorded them, and there is no argument to sort them differently. For orders this is the order of receivedAt. The same order applies when a filter is set: a filter on updatedAt narrows the items, it does not sort them by modification date.
- To read the most recent items, walk the pages backwards with
lastandbefore(see The most recent items below). - To synchronise changes, filter on
updatedAtfrom your last run and walk every page: the changed items can be anywhere in the sequence.
Cursors are opaque: always use a cursor read from a previous response (their format may change over time), never build one yourself. Pages can also be walked backwards with last and before, using pageInfo.startCursor.
Example
The first page, with first: 3 to keep the response short (omit it to get the default 20 items). Note that hasPreviousPage is false. The top-level extensions are the usual rate limiting metadata.
query ordersFirstPage {
orders(first: 3) {
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
edges {
cursor
node {
id
}
}
}
}
{
"data": {
"orders": {
"pageInfo": {
"startCursor": "WzQ1OTZd",
"endCursor": "WzQ1OTld",
"hasNextPage": true,
"hasPreviousPage": false
},
"edges": [
{ "cursor": "WzQ1OTZd", "node": { "id": "4596" } },
{ "cursor": "WzQ1OTdd", "node": { "id": "4597" } },
{ "cursor": "WzQ1OTld", "node": { "id": "4599" } }
]
}
},
"extensions": {
"queryComplexity": 16,
"bucketBalance": 9984,
"bucketRestoreRate": 100
}
}
The second page: pass the previous endCursor as after. Now hasPreviousPage is true.
query ordersSecondPage {
orders(first: 3, after: "WzQ1OTld") {
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
edges {
cursor
node {
id
}
}
}
}
{
"data": {
"orders": {
"pageInfo": {
"startCursor": "WzQ2MDFd",
"endCursor": "WzQ2MDNd",
"hasNextPage": true,
"hasPreviousPage": true
},
"edges": [
{ "cursor": "WzQ2MDFd", "node": { "id": "4601" } },
{ "cursor": "WzQ2MDJd", "node": { "id": "4602" } },
{ "cursor": "WzQ2MDNd", "node": { "id": "4603" } }
]
}
},
"extensions": {
"queryComplexity": 16,
"bucketBalance": 9968,
"bucketRestoreRate": 100
}
}
The most recent items
Because items are in ascending id order, the most recently recorded ones are on the last page: request it with last: 3 and no cursor. Note that hasNextPage is false, and that the items of the page are still in ascending order, the page is not reversed.
query ordersLastPage {
orders(last: 3) {
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
edges {
cursor
node {
id
}
}
}
}
{
"data": {
"orders": {
"pageInfo": {
"startCursor": "WzkzNzFd",
"endCursor": "WzkzNzNd",
"hasNextPage": false,
"hasPreviousPage": true
},
"edges": [
{ "cursor": "WzkzNzFd", "node": { "id": "9371" } },
{ "cursor": "WzkzNzJd", "node": { "id": "9372" } },
{ "cursor": "WzkzNzNd", "node": { "id": "9373" } }
]
}
},
"extensions": {
"queryComplexity": 16,
"bucketBalance": 9984,
"bucketRestoreRate": 100
}
}
The previous page: pass the previous startCursor as before, and keep going while hasPreviousPage is true.
query ordersPreviousPage {
orders(last: 3, before: "WzkzNzFd") {
pageInfo {
startCursor
endCursor
hasNextPage
hasPreviousPage
}
edges {
cursor
node {
id
}
}
}
}
{
"data": {
"orders": {
"pageInfo": {
"startCursor": "WzkzNjhd",
"endCursor": "WzkzNzBd",
"hasNextPage": true,
"hasPreviousPage": true
},
"edges": [
{ "cursor": "WzkzNjhd", "node": { "id": "9368" } },
{ "cursor": "WzkzNjld", "node": { "id": "9369" } },
{ "cursor": "WzkzNzBd", "node": { "id": "9370" } }
]
}
},
"extensions": {
"queryComplexity": 16,
"bucketBalance": 9968,
"bucketRestoreRate": 100
}
}