Balances

Get total balance for a recipient

GET /balances/{Recipient: ID, Email, Public key}

This endpoint returns the total balance and redeemed for a recipient.

JSON

HTTP Status 200 OK

{
    "balance": 234,
    "redeemed": 123
}

Get all balance batches for a recipient

GET /balances/batches/{Recipient: ID, Email, Public key}

This endpoint returns all the balance batches for a recipient.

When a balance is added for a recipient, it is added as a single batch. Whereas the endpoint above just provides the sum of the batches, this endpoint provides the batches individually.

JSON

HTTP Status 200 OK

[
    {
        "batch_id": 123,
        "balance": 234,
        "redeemed": 123,
        "expiry": null,
        "history": [
            {
                "time": "2024-02-02 14:22:59",
                "message": "The quick brown fox jumped over the lazy dog",
                "balance_change": 50
            },
            {
                "time": "2024-12-18 00:12:35",
                "message": "The quick brown fox jumped over the lazy dog",
                "balance_change": 50
            }
        ]
    },
    {
        "batch_id": 123,
        "balance": 234,
        "redeemed": 123,
        "expiry": "2026-05-23 09:43:29",
        "history": [
            {
                "time": "2024-04-28 03:33:57",
                "message": "The quick brown fox jumped over the lazy dog",
                "balance_change": 50
            },
            {
                "time": "2024-06-14 23:19:38",
                "message": "The quick brown fox jumped over the lazy dog",
                "balance_change": 50
            }
        ]
    }
]

Update/increment/decrement balance for recipient

PUT /balances/{Recipient: ID, Email, Public key}

Prefix the balance field with + to increase/add, - to decrease, or nothing to set.
Setting will increment or decrement as necessary to match this value.

The optional batch_id field is used when decrementing the balance, allowing to specify a specific batch to remove balance from.

The expiry and message fields are optional and are used when adding points, or when setting would add a new batch.

JSON

Body content

{
    "balance": "+500",
    "expiry": "2026-03-02 08:20:44",
    "message": "Saepe quia voluptate omnis qui non laboriosam."
}

JSON

Body content

{
    "batch_id": 42,
    "balance": "-100"
}