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.

Headers

HTTP header	Description
`Authorization`	Required. Your API key, after `Basic` and base64-encoded. See 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, a charge, or a subscriber, 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.

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:

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.
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.

Errors

Besides the errors that any request can give, which 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.