Paginate requests

United States

Canada

Clover merchant data sets can be very large. This is why results are returned 10 items at a time by default.

To ensure you are retrieving results as expected, you can add query parameters to your request. These parameters can be used to page through large result sets. The hard limit is 100 items per request.

Three types of merchant data can be requested with paging parameters: charges, orders, and refunds.

Paginate using IDs

Use `ending_before`

Your app may need to display data directly preceding an order, charge, or refund.

The following example shows a request for a specific order and two orders preceding it, a total of three indicated by limit=3.

curl -s "https://scl-sandbox.dev.clover.com/v1/orders? \
limit=3&ending_before=6E72X1BW38A7T" \
--header "Authorization: Bearer {auth_token}"

The response includes the type of object returned (a list), an indication that additional data can be retrieved with subsequent requests (has_more is true), and the data array of order objects. The first order object is the order with the id set as the parameter value.

{
  "object": "list",
  "url": "/v1/orders",
  "has_more": true,
  "data": [
    {
      "id": "6E72X1BW38A7T",
      "amount": 730,
      "currency": "USD",
      "items": [
        {
          "quantity": 1,
          "amount": 730,
          "description": "Mouse pad"
        }
      ]
    },
    {
      "id": "AH4FZD4FXQ07P",
      "amount": 333,
      "currency": "USD"
    },
    {
      "id": "4GW5A6GDWA12J",
      "amount": 10300,
      "currency": "USD",
      "charge": "MZHCSGW4T1KGR",
      "items": [
        {
          "parent": "839XNWK1ZFFQG",
          "amount": 10208,
          "description": "Keyboard"
        },
        {
          "amount": 92,
          "description": "Charity Donation"
        }
      ]
    }
  ]
}

Use `starting_after`

Your app may need to display data that follows a specific order, charge, or refund.

The following example shows a request for a specific order and the four following it, a total of five indicated by limit=5.

curl -s "https://scl-sandbox.dev.clover.com/v1/orders? \ 
starting_after=KHZKKMAFPEPKW&limit=5" \
--header "Authorization: Bearer {auth_token}"

{
  "object": "list",
  "url": "/v1/orders",
  "has_more": true,
  "data": [
    {
      "id": "KHZKKMAFPEPKW",
      "amount": 1899,
      "currency": "USD",
      "items": [
        {
          "quantity": 1,
          "amount": 1899,
          "description": "Mouse"
        }
      ]
    },
    {
      "id": "4GW5WA12WA4SJ",
      "amount": 10300,
      "currency": "USD",
      "charge": "MZHCSGW4T1KGR",
      "items": [
        {
          "parent": "83A6GDWAZFFQG",
          "amount": 10208,
          "description": "USB-C cable"
        }
      ]
    },
    {
      "id": "0XKSYBWV0R9TW",
      "amount": 354,
      "currency": "USD",
      "charge": "ASZ9SGWX8Z2K4",
      "items": [
        {
          "quantity": 1,
          "amount": 354,
          "description": "Capacitor"
        }
      ]
    },
    {
      "id": "JAKQDHRFX5XKM",
      "amount": 411,
      "currency": "USD",
      "charge": "T19YVH7NCV4AM",
      "items": [
        {
          "quantity": 1,
          "amount": 411,
          "description": "Bluetooth interface"
        }
      ]
    }
    {
      "id": "4GW5A6GDWA12J",
      "amount": 10208,
      "currency": "USD",
      "charge": "MZHCSGW4T1KGR",
      "items": [
        {
          "parent": "839XNWK1ZFFQG",
          "amount": 10208,
          "description": "Headphones"
        }
      ]
    }
  ]
}

Request data using date and time

To return information about orders, charges, or refunds relative to a certain date and time, requests can be refined using the created timestamp. You can specify an exact Unix timestamp (in milliseconds) or define an interval in which to search.

The following request retrieves the first five charges created during the specified range.

curl -s "https://scl-sandbox.dev.clover.com/v1/charges? \
created.gt=1585699200000&created.lt=1586044800000&limit=5" \
--header "Authorization: Bearer {auth_token}"

{
  "object": "list",
  "url": "/v1/charges",
  "has_more": true,
  "data": [
    {
      "id": "QNMZE1X9ZVT8T",
      "amount": 347,
      "currency": "usd",
      "created": 1585849840000,
      ...
    },
    {
      "id": "ASZ9SGWX8Z2K4",
      "amount": 354,
      "currency": "usd",
      "created": 1585896286590,
      ...
    },
    {
      "id": "P031SMNP173HG",
      "amount": 462,
      "currency": "usd",
      "created": 1585796590000,
      ...
    },
    {
      "id": "MZHCSGW1T1KGR",
      "amount": 10300,
      "currency": "usd",
      "created": 1585799269800,
      ...
    },
    {
      "id": "N8P065DGDVM72",
      "amount": 10502,
      "currency": "usd",
      "created": 1585699400000,
      ...
    }
  ]
}

Note that the response includes the has_more property to indicate that additional results exist in the range. You can then use the starting_after parameter in a subsequent request to retrieve the next set of results.

Updated about 1 year ago

Paginate using IDs

Use ending_before

Use starting_after

Request data using date and time

Use `ending_before`

Use `starting_after`