---
id: giftcards
title: Gift cards
hide_title: true
description: "How to use gift cards in the cart"
---

import Ingress from "../../../src/components/ingress/ingress.react";

<Ingress title="Using gift cards in the cart">
  Add each gift card to the cart as a separate item with a negative amount and
  VAT set to 0, then read back how much of each card the purchase used.
</Ingress>

Gift cards are most commonly categorized as so-called multi-purpose vouchers, meaning that they allow purchases for products with different tax rates. Since the tax amount cannot be predicted until purchase, the usage of a gift card should be through a separate item with a negative amount and the VAT set to 0.

Gift cards are identified within the cart with the type of value "GiftCard". This identification allows for separate handling of gift cards in calculations and processing.

## Example flow

A common use case to handle gift cards is to authorize the amounts used by each gift card when [validating the order](/docs/checkout/optional/validateorder), and then capture the amounts when the [purchase is completed](/docs/checkout/notificationcallback). If the purchase was unsuccessful for some reason you can listen to [payment failed callback](/docs/checkout/optional/init-checkout-features#paymentfailed) to revert the authorization.

<a
  href="https://static.swimlanes.io/a648b0002673bda6a14b1d2ac78261fb.png"
  target="_blank"
>
  <img
    src="https://static.swimlanes.io/a648b0002673bda6a14b1d2ac78261fb.png"
    alt="Gift Cards example flow"
  />
</a>

{/*
Source for the diagram above, kept so it can be regenerated at swimlanes.io.

title: Gift Cards example flow

Order: User,Walley,Merchant

User -> Walley: Click Complete Purchase

Walley -> Merchant: ValidateOrder Callback

Merchant -> Gift Card system: Authorize
Gift Card system --> Merchant:

Merchant --> Walley:

if: Purchase OK
Walley -> User: Navigate to Thank You Page
Walley -> Merchant: PurchaseCompleted callback

Merchant -> Gift Card system: Capture
Gift Card system --> Merchant:
end

if: Purchase FAILED
Walley -> Merchant: PaymentFailed Callback
Merchant -> Gift Card system: Cancel authorization
Gift Card system --> Merchant:
Merchant --> Walley:
*/}

When you specify a cart you can add one or more gift cards like the following example:

```json
[
  {
    "id": "10001",
    "description": "Product 1",
    "unitPrice": 95.0,
    "quantity": 1,
    "vat": 25.0
  },
  {
    "id": "10002",
    "description": "Gift Card 50",
    "type": "GiftCard",
    "unitPrice": -50.0,
    "quantity": 1,
    "vat": 0.0
  },
  {
    "id": "10003",
    "description": "Gift Card 100",
    "type": "GiftCard",
    "unitPrice": -100.0,
    "quantity": 1,
    "vat": 0.0
  },
  {
    "id": "10004",
    "description": "Gift Card 100",
    "type": "GiftCard",
    "unitPrice": -100.0,
    "quantity": 1,
    "vat": 0.0
  }
]
```

If multiple giftcards are specified, the ones with the lowest amounts are used first, and the ones with higher amount can be used partly or not at all. When you [get checkout information](/docs/checkout/getcheckoutinformation) you will get a response similar to:

```json
{
  "totalAmount": -155.0,
  "items": [
    {
      "id": "10001",
      "description": "Product 1",
      "unitPrice": 95.0,
      "quantity": 1,
      "vat": 25.0
    },
    {
      "id": "10002",
      "description": "Gift Card 50",
      "type": "GiftCard",
      "unitPrice": -50.0,
      "quantity": 1,
      "vat": 0.0,
      "usedAmount": 50.0
    },
    {
      "id": "10003",
      "description": "Gift Card 100",
      "type": "GiftCard",
      "unitPrice": -100.0,
      "quantity": 1,
      "vat": 0.0,
      "usedAmount": 45.0
    },
    {
      "id": "10004",
      "description": "Gift Card 100",
      "type": "GiftCard",
      "unitPrice": -100.0,
      "quantity": 1,
      "vat": 0.0,
      "usedAmount": 0.0
    }
  ]
}
```

Using this information you can decide which gift cards and amounts are used by using `usedAmount`. The remaining amount is calculated by adding `unitPrice` and `usedAmount`. `totalAmount` can be negative if not all gift cards are used and reflects the total remaining amount of the gift cards.