# Seq

Source: <https://docs.gjold.com/v1/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/v1/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 shop is the API key's, and the key needs the `seq` [permission](https://docs.gjold.com/v1/authentication#permissions).

### Headers

- `Authorization`

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

## Response

We answer `200 OK` with a JSON object, as `application/json; charset=UTF-8`, 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/v1/transactions#the-transaction-object), a [charge](https://docs.gjold.com/v1/transactions#charges), or a [subscriber](https://docs.gjold.com/v1/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}` can be returned once for each change, even in one response, or once in all: 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, and fields it doesn't know.

The objects are as their pages describe them, in v1's form: a transaction's card is named for its method, as `method.applepay` for Apple Pay, and its acts name the dashboard user who made them in `"uid"`. See [The transaction object](https://docs.gjold.com/v1/transactions#the-transaction-object).

### Size

A response holds a limited number of changes, and at least one, however large. Call again from the `"seq"` it returned until a call returns no changes. The limit may change, so don't count on it, and 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/v1/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.