# Seq

Source: <https://docs.gjold.com/v2/synchronization/seq>

Read the objects that changed since a position in the shop's sequence: each one whole, as it is now, and the position to read from next.

## Request

**GET** `https://api.gjold.com/v2/{shopid}:seq:{seq}`

- `{seq}` is a position in the sequence: `0` to start from the beginning, and after that, the `"seq"` that your last call returned. It is a decimal integer without leading zeros.

The request has no body. The key needs the `seq` [permission](https://docs.gjold.com/v2/authentication#permissions).

### Headers

- `Authorization`

  **Required.** Your API key, after `Basic` and base64-encoded. See [Authentication](https://docs.gjold.com/v2/authentication).

## Response

We answer `200 OK` with a JSON object, without white space:

| Field | Type | Description |
|---|---|---|
| `changes` | array of objects | The objects that changed after position `{seq}`, in the order of the sequence: each a [transaction](https://docs.gjold.com/v2/transactions#the-transaction-object), a [charge](https://docs.gjold.com/v2/transactions#charges), or a [subscriber](https://docs.gjold.com/v2/subscribers#the-subscriber-object), as its `"type"` says. Empty when there is nothing new. |
| `seq` | integer | The position to read from next, once you have applied the changes. The same as `{seq}` when there is nothing new. |

```
{
    "changes": [
        {
            "type": "transaction",
            "id": 378,
            "rev": 3,
            …
        },
        {
            "type": "subscriber",
            "id": 19,
            "rev": 2,
            …
        },
        {
            "type": "charge",
            "id": 379,
            "rev": 1,
            …
        }
    ],
    "seq": 164
}
```

Each change is the object as it is when you call, whole, not the difference from before. An object that changed several times since `{seq}` is usually returned once, but can be returned more than once, even in one response: apply each copy only if its `"rev"` is higher than the one you have, and the result is the same. A client must skip a `"type"` it doesn't know.

### Size

A response holds as many changes as fit in 64 KiB, and at least one, however large. Call again from the `"seq"` it returned until a call returns no changes. The limit may change, so read the response whole, whatever its length.

### Order

The sequence keeps the order that merging needs:

1. A transaction first appears after every transaction with a lower `"id"`, and a subscriber after every subscriber with a lower one, so there are no gaps.
2. A charge first appears after its subscriber, at the subscriber's `"rev"` that the charge names, or a later one.

These hold for the sequence read from `0`. See [What seq guarantees](https://docs.gjold.com/notes/synchronization#what-seq-guarantees).

## Errors

Besides the errors that any request can give, which [Errors](https://docs.gjold.com/v2/errors) lists:

| Status and message | Description |
|---|---|
| `404 Not Found` | `{seq}` is not a decimal integer, such as `01` or `-1`. |

Seq doesn't check that `{seq}` is a position it returned. One beyond the end of the sequence returns no changes and the same `"seq"`, as if you were up to date, until the shop has had that many changes. So store only a `"seq"` that seq returned, and never add to it yourself.

Seq is safe to retry, and to call as often as you like: it changes nothing. A call that returns no changes costs us little, so a timer that calls it every minute or so, as a safety net beside pings, is fine.