◐OmniCart Docs
View as Markdown

Gift Cards & Store Credit

Two ways to hold a balance for a customer, and one mechanism underneath.

They are the same thing, owned differently#

Issuing a gift card creates a store credit account behind it. That account holds the card's value.

A gift card is a balance reached by a code. It belongs to nobody. Store credit belongs to one customer, in one currency.

Everything else follows from that difference.

Gift card Store credit
Reached by its code the customer, in the cart's currency
Works at guest checkout Yes No — the cart needs a customer
Amount applied the whole available balance an amount you choose
More than one on a cart Yes No — applying again replaces the last
Wrong currency refused, naming the card no balance found
Expiry optional expiry date none

Spending happens in two steps#

This is the part that surprises people.

Applying a balance to a cart does not spend it. It records that the balance is intended for this cart. The balance is untouched. A cart can sit that way for as long as the customer leaves it.

The balance moves when the order completes, just before payment is taken. Gift cards and store credit are drawn down together at that moment.

If payment fails, the deduction is undone. A failed checkout never consumes a balance. So when a customer reports credit lost on an order that did not go through, the balance should still be there. Check it before you issue more.

Applied credit is capped at the order total. The remainder stays on the account.

This is the difference from a discount code. A code is used up whole, so a $20 code against a $15 order throws away $5. A $20 balance against a $15 order leaves $5.

Turning a gift card into store credit#

A customer with an account can claim a gift card. The balance moves out of the card and into their own credit. After that it is ordinary store credit: no code to keep, no expiry.

Claiming is refused in three cases: the customer is a guest, the balance already belongs to someone, or the balance is zero.

Refunds#

A refund can be returned as store credit. It lands as a new entry on the customer's account, naming the order it came from.

Only registered customers can be refunded to store credit. A guest has no account to hold it. The refund is refused rather than dropped silently. Use the original payment method for guests.

Reading a balance#

Every movement is recorded separately: money added, money spent, money refunded. Each entry carries the reason it happened.

The account shows the total. The transaction history shows how it got that way. That is what answers "why is this lower than the customer expects".

When you add credit, write a note. It is what someone reads months later.

When it is switched on#

Gift cards and store credit are enabled per store. Where they are switched off, none of these endpoints exist and the screens are absent. If the feature seems missing rather than broken, that is why.

Troubleshooting#

Store credit will not apply. Check the cart has a customer attached. Guest carts cannot use store credit, but they can use a gift card. Then check the currency. A balance in one currency is invisible to a cart in another.

The customer expected part of a gift card to be used. Not possible. A gift card applies its whole available balance, capped at the order total. To spend a set amount, claim the card into store credit first, then apply that amount.

A gift card is refused as already applied. It is on the cart already. Remove it and apply it again if the balance looks wrong.

A balance did not go down after checkout. Check the order actually completed. Until it does, the balance is reserved, not spent.

A balance went down and the customer says they did not order. The transaction history names the order that consumed it.

Endpoints#