Skip to content

Stream API

Follow new and changed orders across your platform with a pointer.

The Stream API gives you every new and changed order of your platform, in the order they changed. Use it to keep your own systems in sync, such as a data warehouse, a reconciliation or a fraud monitor, without searching for changes. To find specific orders, use the Search API instead.

Authentication

The order stream holds the orders of all merchants on your platform, so it's for admins only. Authenticate with an admin API key or an admin user's token, with GET permission on /admin/stream/orders/. See Authentication and Permissions. A merchant's or project's API key gets 403 Forbidden.

How the stream works

Every change to an order puts the order at the end of the stream, with a new, higher sequence number. The stream only holds the last state of each order: when an order changes again, it moves to the end with a new sequence number, and its earlier entry is gone. So sequence numbers have gaps, and you see each order as often as it changed while you weren't reading.

You keep a pointer: the highest sequence number you've processed. Each request returns the orders after your pointer.

sequence diagram

Read the stream

Start at pointer 0

curl "https://api.example.com/v1/admin/stream/orders/?pointer=0&limit=2" \
  --user "$API_KEY:"
{
  "results": [
    {
      "sequence": 1,
      "data": {
        "id": "738709ef-d555-4720-9e49-05b1c7f14657",
        "status": "completed",
        "transactions": [ ... ]
      }
    },
    {
      "sequence": 3,
      "data": {
        "id": "c87d5e85-06a9-441d-bf93-ab53d919aba2",
        "status": "processing"
      }
    }
  ]
}

The response is shortened. Each result has the sequence number and the order in data, with its transactions. See Read the order stream in the API reference for all fields.

Process the orders, then move the pointer

Process the results in order, then store the highest sequence you received as your pointer. In the example, that's 3.

Ask for the next orders

curl "https://api.example.com/v1/admin/stream/orders/?pointer=3&limit=2" \
  --user "$API_KEY:"

When results is empty, you're up to date. Wait a while, then ask again with the same pointer.

Pointers and limits

Send the highest sequence you've processed as pointer, and get up to limit orders with a higher sequence number: 100 by default, at most 250.

  • An order shows up in the stream a few seconds after it changed. Ginger holds new entries back until every earlier change is stored, so you never miss an order when you move your pointer forward.
  • Store your pointer after processing, so you can carry on after a restart. When in doubt, read from an older pointer: you get some orders again, with their latest state.
  • To rebuild your copy from scratch, start again at pointer 0.
  • An order's status is in the stream as it changes. See Statuses for what each status means.

API reference

See Read the order stream for the parameters and the fields of the order.