Foundations

Rate Limits

When making a request for data, Rutter will paginate the returned data if the data set is too large. You'll know when pagination has occurred if the next_cursor field is supplied. The next_cursor is a generated base64 encoding of the timestamp and id of the next entity (e.g. an order, a transaction).

To proceed to the next page, set the query parameter cursor to the next_cursor value. A response without a next_cursor field can either signify the last page or that the response was small enough where pagination was not required.

Example

Below is an example workflow utilizing the next_cursor field by first fetching all orders:

curl --request GET \
     --url 'https://production.rutterapi.com/versioned/orders?access_token=access_token' \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic your_base64_encoded_client_id_and_api_key' \
     --header 'X-Rutter-Version: 2023-03-14'

This will return the following response with the next_cursor field located at the bottom, indicating that there is more data to fetch from subsequent pages.

{
  "orders": [
    {
      "id": "0f22c735-57dd-4954-9084-68e41c17b573",
      "platform_id": "7513594",
      "order_number": "1001",
      "status": "active",
      "payment_status": "refunded",
      "fulfillment_status": "partial",
      "fulfillments": [
        {
          "order_id": "0f22c735-57dd-4954-9084-68e41c17b573",
          "carrier": "China Post",
          "service": "One Day Delivery",
          "tracking_number": "112345Z2345",
          "tracking_url": "http://track-chinapost.com/startairmail.php?code=112345Z2345",
          "line_items": [
            {
              "id": "123",
              "product_id": "78f91173-d270-41a9-b03d-e18ac7cc13e0",
              "variant_id": "819f582e-af2d-44c9-8d1e-e352c581a4d4",
              "title": "IPod Nano",
              "price": 250.00,
              "iso_currency_code": "USD",
              "sku": "IPOD-342-N",
              "quantity": 1
            }
          ]
        }
      ],
      "line_items": [
        {
          "id": "123",
          "product_id": "78f91173-d270-41a9-b03d-e18ac7cc13e0",
          "variant_id": "819f582e-af2d-44c9-8d1e-e352c581a4d4",
          "unit_cost": 250.00,
          "price": 500.00,
          "quantity": 2,
          "iso_currency_code": "USD",
          "sku": "IPOD-342-N",
          "title": "IPod Nano",
        }
      ],
      "refunds": [
        {
          "line_items": [
            {
              "line_item_id": "123",
              "quantity": 1
            }
          ]
        }
      ],
      "billing_address": {
        "address1": "123 Amoebobacterieae St",
        "address2": null,
        "city": "Ottawa",
        "first_name": "Bob",
        "last_name": "Bobsen",
        "phone": "555-625-1199",
        "postal_code": "K2P0V6",
        "country_code": "CA",
        "region": "ON"
      },
      "shipping_address": {
        "address1": "123 Amoebobacterieae St",
        "address2": null,
        "city": "Ottawa",
        "first_name": "Bob",
        "last_name": "Bobsen",
        "phone": "555-625-1199",
        "postal_code": "K2P0V6",
        "country_code": "CA",
        "region": "ON"
      },
      "customer": {
        "id": "207119551",
        "email": "bob.norman@hostmail.com",
        "first_name": "Bob",
        "last_name": "Norman",
        "orders_count": "1",
        "verified_email": true,
        "phone": "+13125551212"
      },
      "total_shipping": 4.99,
      "total_discount": 0,
      "total_tax": 14.28,
      "total_price": 519.27,
      "iso_currency_code": "USD",
      "created_at": "2016-06-23T09:09:34.752Z",
      "updated_at": "2016-06-23T09:10:02.798Z"
    }
  ],
  "connection": {
    "platform": "Shopify",
    "id": "7ab6d4c4-24bb-45f9-851d-64cfdab8349e",
    "orgId": "940dgsed-1abe-4698-8d4e-d59cf69df64c"
  },
 "next_cursor": "MTYxMDExOTU2Nnx8YWFlOGI4YtM2RmMi00OGZhLThhNGEtNmM1OWJkNjc3NTBm"
}

You can then populate the cursor query parameter with the value of the next_cursor in order to continue fetching the data from Rutter:

curl --request GET \
     --url 'https://production.rutterapi.com/versioned/orders?access_token=access_token&cursor=MTYxMDExOTU2Nnx8YWFlOGI4YtM2RmMi00OGZhLThhNGEtNmM1OWJkNjc3NTBm' \
     --header 'Accept: application/json' \
     --header 'Authorization: Basic your_encoded_client_id_and_api_key' \
     --header 'X-Rutter-Version: 2023-03-14'

Repeat the steps until the response no longer contains the next_cursor field to ensure all data has been fetched.

Please also see the Python example found in the Ingestion Pipeline guide on how to handle pages when fetching data.