Redemptions & top-ups

The createBalanceAdjustment mutation handles all balance adjustment against an existing card.

A line item represents the balance adjustment action that took place and links it with the transaction responsible for the causing the balance adjustment.

To create a balance adjustment for a card in Toggle, make a mutation request to createBalanceAdjustment.

Redemptions (debit a gift card)

To make a redemption adjustment, you can pass a negative value, e.g. “-100”.

API call

mutation(
  $currency: String
  $value: Int
  $card_reference: String!
  $merchant_id: Int!
  $merchant_transaction_reference: String
  $unit_epos_reference: String!
) {
  createBalanceAdjustment(
    currency: $currency
    card_reference: $card_reference
    value: $value
    merchant_id: $merchant_id
    merchant_transaction_reference: $merchant_transaction_reference
    unit_epos_reference : $unit_epos_reference
  ) {
    id
    value
    LineItem {
      Card {
        id
        card_reference
        balance
        initial_balance
        created_at
        updated_at
      }
    },
    ValueSplit{
        tender,
        discount
    }
  }
}

Variables

{
	"currency": "GBP",
	"card_reference": "6301190001944443757",
	"unit_epos_reference": "epos01",
	"value": -10,
	"merchant_id": 26,
	"merchant_transaction_reference": "my-own-transaction-reference"
}

Response

{
  "data": {
    "createBalanceAdjustment": {
      "id": 988008,
      "value": -10,
      "LineItem": {
        "Card": {
          "id": 529113,
          "card_reference": "6301190001944443757",
          "balance": 80,
          "initial_balance": 1000,
          "created_at": "2021-06-05 16:19:52",
          "updated_at": "2021-06-05 16:19:52"
        }
      },
      "ValueSplit": {
        "tender": 800, // £8 tender
        "discount": 200 // £2 discount
      }
    }
  }
}

Take a look at the examples on the API playground >

Tender vs Discount

The API response we send back after a redemption will tell you whether to treat it as a discount (money-off, reducing sales tax/VAT) or as tender (treat the same as cash). In some cases, a redemption could be a mixture of discount and tender.

"ValueSplit": {
   "tender": 800, // £8 tender
   "discount": 200 // £2 discount
 }

The ValueSplit object tells you how much to take off the guests bill as discount and how much to treat as payment tender.

This is important because typically sales tax (e.g. VAT) will be calculated on the basket total after any discounts are applied.

So if gift card is given away and redeemed, the redemption should reduce the VAT on the resulting basket total.

In most cases, gifts will be one or other: either 100% tender or 100% discount. However, it's possible that, as per the example above, there might be a mixture of tender and discount on a card (e.g. a £10 card that was issued with a £2 discount).

You can read more about VAT and gift cards on our guide here >

Top-ups (credit a gift card)

For a top-up, simply pass a positive value to the createBalanceAdjustment mutation.