How to use gift cards in the cart

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, and then capture the amounts when the purchase is completed. If the puchase was unsuccessful for some reason you can listen to payment failed callback to revert the authorization.

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

[
  {
    "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 you will get a response similar to:

{
  "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.