# Balance events

The balance event object represents a change in a voucher balance and is returned with each of the actions associated with codes which are currently activating, [topping up](/reference/codes.md#topup-voucher) and [redemption](/reference/codes.md#redeem-voucher).

Each event has a `type` attribute which provides context to the reason for the event, every event associated with a voucher provides a reference to the row with the `rowID` and the `orderID` attributes which can be used to expand and get further information on the original sale of the voucher.

To understand what each type of event means and when they can occur you can read the [list of event types here.](/reference/balance-events/types-of-event.md)

#### Common use case

A common use case is to track voucher balances by  getting all balance events. If you're polling for new balance events you should [filter](/filtering.md) the created attribute for greater than or equal to the most recent balance event.

## List balance events

<mark style="color:blue;">`GET`</mark> `https://api.giftpro.co.uk/balance_events/`

Returns a list of the last 50 balance events with the most recently created first. To view more events take a look at [pagination](https://docs.giftpro.co.uk/#pagination) and you can use `created` to filter, read more about [filtering here](https://docs.giftpro.co.uk/#filtering).

#### Query Parameters

| Name    | Type   | Description |
| ------- | ------ | ----------- |
| created | String |             |

{% tabs %}
{% tab title="200: OK " %}

```json
{
  "data": [
    {
      "eventID": 556697,
      "domainID": 479,
      "locationID": 1204,
      "amount": 99.95,
      "currencyCode": "GBP",
      "type": "Topup",
      "startingBalance": 50,
      "balance": 0,
      "currencies": {
          "EUR": {
              "exchangeRate": 1.10,
              "amount": -109.95,
              "balance": 0
          },
          "GBP": {
              "exchangeRate": 1.00,
              "amount": -99.95,
              "balance": 0
          }
      },
      "confirmed": true,
      "created": "2019-12-07 22:19:02",
      "row": {
        "code": "1234EXAMPLECODE",
        "type": "Voucher",
        "links": {
          "self": "/codes/1234EXAMPLECODE/"
        }
      },
      "order": {
          "orderID": 623578,
          "links": {
              "self": "/orders/623578/"
          }
      }
    },
    {...}
  ]
}
```

{% endtab %}
{% endtabs %}

## Reverse

<mark style="color:green;">`POST`</mark> `https://api.giftpro.co.uk/balance_events/{eventID}/reverse/`

Reversing an event will create and return a new balance event, this is the recommended way to undo an already confirmed event and can be done at any time after the event is confirmed.

You can only reverse an event once.

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}

{% tab title="403: Forbidden " %}
{% tabs %}
{% tab title="Second Tab" %}

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

|                        |   |   |
| ---------------------- | - | - |
| reversal\_not\_allowed |   |   |
|                        |   |   |
|                        |   |   |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.giftpro.co.uk/reference/balance-events.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.