Fetch sold and returned gift cards

A gift card can be sold or returned. It can be returned only if a gift card is not redeemed, partially redeemed, or expired.

To get details for sold and returned 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.

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: Find sold gift cards

Retrieve sold gift cards from the stored purchase history. Iterate through the product list for each purchase, and search for the GIFTCARD product type with refund as false.

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

Example: In the stored purchase information response, search for the GIFTCARD product type with refund as false.

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: Find returned gift cards

Retrieve returned gift cards from the stored purchase history. Iterate through the product list for each purchase and search for the GIFTCARD product type with refund as true.

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

Example: In the stored purchase information response, search for the GIFTCARD product type with refund as true .

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": "2252b412-f531-405b-a073-1b3b9f2bbdd4",
50
      "groupedVatAmounts": {
51
        "12.0": 1000,
52
        "25.0": 100
53
      },
54
      "refund": true
55
    },
56
    ...
57
  ],
58
  "firstPurchaseHash": "1605774904230GV2NDCpCEeuqwlj953Nabw",
59
  "lastPurchaseHash": "1605882295421KEx7SCs8EeuzPiiU-CPahg",
60
  "linkUrls": []
61
}

Bookkeeping of sold and returned gift cards

As a general rule, the sale of gift cards should be accounted as liability. See Selling gift cards.

Related information