> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Gift Cards
Gift card payments are supported directly through the API with support for split
tender across traditional payment methods and gift cards, as well as automatic reversal.
## Setup
Currently, gift cards are supported through Qwikcilver only. Please refer to the
[Qwikcilver][qwikcilver] for further details on how to set up your connector
## API endpoints
The API for gift cards consists of the following endpoints and API features.
* [Manage gift card services](/reference/gift-card-services)
* [Check gift card balances](/reference/gift-cards/list-gift-card-balances)
* [Manage stored gift cards](/reference/gift-cards) and associate them with buyers
* [Enhancements to the transaction endpoints](/reference/transactions/new-transaction) to allow for payments with one or more gift cards,
including the ability to split a payment across gift cards and other payment methods.
## Reversals
As part of processing gift cards, the ability to automatically revert an authorized payment method or redeemed gift card before it is reverted is supported.
The logic for this feature is as follows.
* When a transaction occurs, regular payment methods are authorized (or captured)
first, depending on their support for delayed capture.
* Gift cards are only redeemed after the (optional) regular payment method has
succeeded to authorize/capture.
* When no regular payment method is present, gift cards are always redeemed.
* In the case that any of the gift cards failed to redeem, any redemptions of other gift cards
and regular payments are reverted.
* In the case of Qwikcilver, gift cards are processed in a batch mode so any failed
gift card automatically results in all gift cards failing.
* In the case of an authorized or captured regular payment method, the transaction is
reverted by either voiding the authorization or refunding a capture.
In some cases, gift card redemptions are not reverted. Please see the anti-fraud section below.
### Outcome
There are two fields returned by the transaction API which allows you to
quickly understand if the original intent of a transaction was met.
* The `multi_tender` (boolean) field indicates if the
transaction included more than one tender.
* The `intent_outcome` (enum) field indicates if the
original intent (`authorize` / `capture`) was met. This field is set
to either `pending` if the transaction has not completed yet, `succeeded` in the case
all tenders were processed successfully, and `failed` if any of them failed.
This field does not change value after the `succeeded` or `failed` status has been achieved,
even if the transaction is subsequently captured, voided, or refunded in any way.
```json theme={"system"}
{
"type": "transaction",
"id": "89bdaeeb-4be8-4ab7-a9e2-6f2c3da5f2d0",
"intent": "capture",
"multi_tender": true,
"intent_outcome": "succeeded",
...
}
```
### Reversals and anti-fraud reviews
There is a key difference in how reversals are handled when a transaction encounters
any kind of halt in processing. This happens when the transaction is held in
anti-fraud review.
In these situations, if the approval fails, or if the transaction is rejected,
the gift cards are **not refunded**. The reason for this is that because of the
time delay between the redemption and refund the user may no longer have the gift card
at hand anymore.
## Gift card usage data
Each stored gift card tracks usage statistics that help you determine which card to preselect at checkout or prioritize in your UI.
| Field | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `last_used_at` | The date and time when this gift card was most recently used in any transaction. `null` if the gift card has not been used yet. |
| `usage_count` | The number of times this gift card has been used in any transaction. |
| `cit_last_used_at` | The date and time when this gift card was most recently used in a customer-initiated transaction (CIT). `null` if the gift card has not been used in a CIT yet. |
| `cit_usage_count` | The number of times this gift card has been used in a customer-initiated transaction (CIT). |
Usage data is not back-filled. Only transactions processed after this feature was enabled are counted.
### Sorting by usage
The [list buyer gift cards](/reference/gift-cards/list-buyer-gift-cards) endpoint supports a `sort_by` query parameter to order results by any of the four usage fields.
```
GET /buyers/gift-cards?sort_by=last_used_at
GET /buyers/gift-cards?sort_by=cit_last_used_at
```
Results are returned in descending order by default, so the most recently used or most frequently used gift card appears first. To sort in ascending order, set `order_by=asc`.
## Stored gift card filtering
The API automatically removes any gift cards stored for a buyer with a zero balance
or an expiry date in the past. When you add a new card, you may receive an error informing
you that you've hit the limit of the number of stored cards (defaults to 10).
You need to actively call the [`GET /buyers/gift-cards`](/reference/gift-cards/list-buyer-gift-cards) to clear out any expired
and zero balance gift cards.
## Limits
By default, the number of gift cards that can be used at the same time is limited to 10. This limit
applies to the APIs for querying gift card balances, processing gift cards, as well as the
number of gift cards that can be stored on a buyer.
To change this limit, reach out to the support team.
In the event of the limit being exceeded, a `HTTP 400` response with an error message
`The buyer's gift card count has already reached the maximum limit of 10 gift cards` is returned.
## Pending features
The following features are still in development and are added in the coming weeks.
* Support for declines using Flow for transactions not involving scheme cards.
[qwikcilver]: /connections/payments/qwikcilver-gift-card