Fetch expired and redeemed gift cards

A gift card can be expired when it passes its expiry date. It can also be redeemed when has been used and has a balance of zero.

To get details for expired and redeemed gift cards, you first use the Purchase API to fetch purchase history and gift card UUIDs. Then you use the Gift Card API to access gift card details.

Try out in Postman

Download Postman collection for this user guide and import it in Postman.

See the following for steps to retrieve details for _expired_ gift cards that have passed expiry date and _redeemed_ gift cards that have been used and have a balance of zero.

Prerequisites

  • Authorisation setup with a valid authorisation token and the access scope READ:PURCHASE.

Step 1: Fetch purchase history

Fetch and store the purchase history at regular intervals. It's recommended to retrieve the data during low-peak traffic hours, for example at midnight. In the request parameters, set the startDate to the most recent time of the data retrieval.

1
GET /purchases/v2?startDate={startDate}

Example: This request fetches purchase information from 19 November 2020 and onwards.

1
GET /purchases/v2/?startDate=2020-11-19

Step 2: Fetch gift card UUIDs

In the stored purchase history, retrieve the giftcardUuid for all purchases made by gift cards. Iterate through the product list for each purchase and search for the GIFTCARD product type.

Tip: In the response, you can search through all product lists in all purchases using a JSONPath $..purchases[*].products[?(@.type=="GIFTCARD")].details.

Example: In the stored purchase information response, search for the GIFTCARD product type.

1
{
2
  "purchases": [
3
    {
4
      "source": "POS",
5
      "purchaseUUID": "GV2NDCpCEeuqwlj953Nabw",
6
      "amount": 49950,
7
      "vatAmount": 9990,
8
      "taxAmount": 9990,
9
      "country": "SE",
10
      "currency": "SEK",
11
      "timestamp": "2020-11-19T08:35:04.230+0000",
12
      "purchaseNumber": 12496,
13
      "globalPurchaseNumber": 12496,
14
      "userDisplayName": "iZettle DEMO SE",
15
      "userId": 872591,
16
      "organizationId": 6394297,
17
      "products": [
18
        {
19
          "quantity": "1",
20
          "productUuid": "5c84a1a6-96d0-11eb-b3d5-7961f4378b1d",
21
          "variantUuid": "5c84a1a6-96d0-11eb-b3d5-7961f4378b1d",
22
          "taxRates": [],
23
          "taxExempt": false,
24
          "unitPrice": 5000,
25
          "rowTaxableAmount": 5000,
26
          "name": "Presentkort",
27
          "fromLocationUuid": "d3f75320-f385-11e6-a947-77fb88b8b0b0",
28
          "toLocationUuid": "d3f77a30-f385-11e6-ad9a-8d19b91557b0",
29
          "autoGenerated": false,
30
          "id": "0",
31
          "type": "GIFTCARD",
32
          "grossValue": 5000,
33
          "details": {
34
            "giftcardUuid": "5C84A1A6-96D0-11EB-B3D5-7961F4378B1D"
35
          },
36
          "libraryProduct": true
37
        },
38
        ...
39
      ],
40
      "discounts": [
41
        ...
42
      ],
43
      "payments": [
44
        ...
45
      ],
46
      ...
47
      "created": "2020-11-20T08:36:56.419+0000",
48
      "refunded": false,
49
      "purchaseUUID1": "5f5bb54a-96d0-11eb-b2d4-7860f5368a1c",
50
      "groupedVatAmounts": {},
51
      "refund": false
52
    },
53
    ...
54
  ],
55
  "firstPurchaseHash": "1605774904230GV2NDCpCEeuqwlj953Nabw",
56
  "lastPurchaseHash": "1605882295421KEx7SCs8EeuzPiiU-CPahg",
57
  "linkUrls": []
58
}

Step 3: Access gift card details

  1. For Uuid, use the retrieved giftcardUuid from the previous step to access gift card details.

Example: This request fetches the details for the gift card with giftcardUuid 5c84a1a6-96d0-11eb-b3d5-7961f4378b1d.

1
GET /organizations/self/giftcards/external/5c84a1a6-96d0-11eb-b3d5-7961f4378b1d

Response: Since the values for initial and remaining amounts are the same (5000), no redemptions have been done.

1
{
2
    "uuid": "5c84a1a6-96d0-11eb-b3d5-7961f4378b1d",
3
    "created": "2021-04-06",
4
    "validTo": "2023-04-06",
5
    "initialAmount": 5000,
6
    "remainingAmount": 5000
7
}
  1. Repeat request in 1 to access details for all fetched gift cards.

Bookkeeping of expired and redeemed gift cards

As a general rule, the value of expired gift cards and the redemption of gift cards should be accounted as revenue. See Selling gift cards.

Related information