Gift cards
Gift cards, their redemption into store credit, and the void.
A gift card is a code that moves money into a customer's credit balance when it is redeemed. Cards and credit share the one ledger. See Store credit, gift cards and credit notes.
List gift cards
/api/v1/kahunacart/gift-cards
Every gift card with its value, its state and the last four characters of its code. The code itself is never returned by any read: the store keeps only a SHA-256 of it, and the one plaintext copy went to the buyer in the email.
Parameters
| Name | Type | Description |
|---|---|---|
| status optional | string |
Only cards in this state; omit for all of them
One of:
active, redeemed, void |
| sort optional | string |
A column to sort the whole list by before it is paged; leave out for the usual order
One of:
code, value, status, issued, order |
| dir optional | string |
One of:
asc, descDefault:
asc |
| q optional | string | Words to search for in the last four characters of the code, the order number and the state; every word has to be there, in any order. Applied before the sort and the page, and total counts what it found |
| page optional | integer |
At least 1.
Default:
1 |
Issue a gift card
/api/v1/kahunacart/gift-cards
Mint a card by hand — a goodwill gesture, a promotion, a card sold over the counter. The response carries the plaintext code, once and only here, because the store keeps a hash and this is the single moment the code exists outside the buyer's inbox. Give it to the recipient before you close the response.
Parameters
| Name | Type | Description |
|---|---|---|
| amount optional | string | What the card is worth, as a decimal in the card's currency, which is the store currency unless `currency` says otherwise |
| amount_minor optional | integer | The same value in minor units of the card's currency; use this or amount, not both |
| currency optional | string | The card's currency, a currency the store sells in; the store currency when left out. A card is in one currency and is refused by name on an order in another |
| note optional | string | Why it was issued. Kept with the card and with its ledger row |
Redeem a gift card for a customer
/api/v1/kahunacart/gift-cards/redeem
Put a card's value into a customer's store credit on their behalf — the support-desk case, for somebody who cannot type the code in themselves. Redeeming twice credits once, whichever path is used. Refuses a code that is unknown, already used, expired, or in a different currency, and says which.
Parameters
| Name | Type | Description |
|---|---|---|
| code required | string | The code as the customer reads it; spacing and dashes do not matter |
| customer_id required | integer | Whose account the value lands in |
| order_id optional | integer | The order the code was quoted against, when there is one. Its currency is the one the card is checked against; an order that does not exist is a 404. Without one the card's own currency is used |
Void a gift card
/api/v1/kahunacart/gift-cards/{id}/void
Cancel a card that has not been redeemed and take its value back off the ledger. A card that has already been redeemed is refused: the money is in somebody's account by then, and taking it back is an adjustment with a reason on it rather than a cancellation.
Parameters
| Name | Type | Description |
|---|---|---|
| id required | integer | Gift card id |
| reason optional | string | Why it was cancelled; kept with the ledger row |
Redeeming is what turns a card into credit, so a voided card that was already redeemed leaves the credit where it is. Voiding is permanent.