Fetch sold and returned gift cards
The Zettle Gift Card API is used to programmatically fetch details for a gift card. It's usually used together with the Purchase API to provide additional purchasing information. The gift card data can be used for sales reporting, bookkeeping, and accounting integrations.
To get gift card statuses and amount values, 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. A gift card can be sold or returned. It can be returned only if a gift card is not redeemed, partially redeemed, or expired.
See the following for steps to retrieve gift card details for sold and returned gift cards.
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.
1GET /purchases/v2?startDate={startDate}
Example: This request fetches purchase information from 19 November 2020 and onwards.
1GET /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[*].products[?(@type==GIFTCARD)].refund[false]
.
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": true37},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": false52},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[*].products[?(@type==GIFTCARD)].refund[true]
.
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": true37},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": 10053},54"refund": true55},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.