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

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.

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 the created attribute for greater than or equal to the most recent balance event.

List balance events

GET 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 and you can use created to filter, read more about filtering here.

Query Parameters

Name	Type	Description
created	String

200: OK

{
  "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/"
          }
      }
    },
    {...}
  ]
}

Reverse

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

200: OK

403: Forbidden