Reversals

When either creating an order or redeeming a card, you may also need to support the functionality to reverse that action. For example, if a staff member selling or redeeming the card on-site needs to undo what they did - which could be a gift card sale or a balnace adjustment.

To reverse a transaction, make a mutation request to createReversal. You will need to pass in the Toggle line_item_id of the transaction you want to reverse.

mutation CreateReversal {
    createReversal(
        merchant_transaction_reference: "abc-def-ghi-123"
        merchant_id: 24
        unit_epos_reference: "Epos01"
        ReversalItems: { 
            line_item_id: 11001614 
            shipping_refund: false 
        }
    ) {
        id
        value
        LineItems {
            value
            Card {
                card_reference
                balance
            }
        }
    }
}

What line item ID should I use?

There are 2 ways you can get the line_item_id.

1. You can do a get line_item_id call

To find this, you'll first need to make another query to fetch this for the transaction that you are trying to reverse, using the merchant_transaction_reference you passed in the original call.

API query

query LineItems {
    LineItems(merchant_transaction_reference: "abc-def-123-123-423-aaasde4") {
        data {
            id
        }
    }
}

This will give you the line item ID for the transaction you are trying to reverse.

1. Whenever you create or balance adjust a card, you can add the ID to the query and have it returned in the response

This will require you to store that ID against the transaction, then later surface it to us for the reversal.

What merchant transaction reference should I use?

The merchant_transaction_reference you pass in for the reversal is expected to be a uniquely generated reference (e.g. an identifier of the reversal transaction on the till).

If your system doesn't create transaction references for reversals, then you could potentially just append "-REVERSAL" on the end of the original reference. e.g. "test-123-123-123-REVERSAL"

This use-case is aimed at book-keepers and for troubleshooting, whereby if someone downloaded, say, a CSV list of till transactions (e.g. card sales, redemptions, reversals etc.) and each has a unique till transaction identifier, then if someone pulled down an equivalent CSV list of balance adjustments on the Toggle side, someone could - if needs be - match them up with your unique identifier for each one.

What epos_reference should I use?

If this is reversed at a specific location, the location that is performing the reversal should be provided. This field is optional though, as some reversals are done centrally rather than at site.

What about partial refunds?

With the CreateReversal mutation you can only refund the full value of the LineItem you are wanting to refund.

In order to do partial refunds you would need to refund the whole line item and then subsequently create a new balance adjustment with the corrected value.