Purchase concept
The Zettle Purchase service provides read-only information about purchases made through Zettle. For example, the Purchase API lets you build integrations between Zettle and e-commerce systems, for exchange of purchase transaction data. Accounting integrations as well use Purchase API.
To integrate with Zettle, you need to access merchant data. To gain access, you need to set up authorisation for the merchant to grant access to the data. See Authorisation OAuth API.
In general a purchase means acquisition of an item or service that is typically paid for through an exchange of money or other asset. In the purchase API, a purchase represents a receipt. It contains information about sold items, and is immutable, meaning the information cannot be changed.
Through the Purchase API, purchase information is passed from the Purchase service. The information includes one or several payments received, products sold, taxes, discounts and so on. Refunds are represented by the same information model.
See the following example of the purchase information. For details about request/response information, see the Purchase API reference.
The following request returns information for a purchase with a given UUID. The source
attribute shows the origin of
the purchase. This can be the Zettle POS app, a Zettle Payments SDK, or an online webshop.
1GET /purchase/v2/{purchaseUuid}
Response:
1{2"source": "POS",3"purchaseUUID": "WJwt5j7kEeuecKKsB1sX_Q",4"purchaseUUID1": "589c2de6-3ee4-11eb-9e70-a2ac075b17fd",5"amount": 70000,6"vatAmount": 14000,7"country": "SE",8"currency": "SEK",9"timestamp": "2020-12-15T14:46:43.592+0000",10"gpsCoordinates": {11"longitude": 19.80452501310729,12"latitude": 66.609375,13"accuracyMeters": 16514},15"purchaseNumber": 1366,16"globalPurchaseNumber": 1366,17"userDisplayName": "Sara Johansson",18"userId": 11111,19"organizationId": 11111,20"products": [21{22"quantity": "1",23"productUuid": "2f2a8d60-9c76-11e5-8a3b-82916dc77adc",24"variantUuid": "234ee5f0-b188-11e5-aa17-721c907d3875",25"vatPercentage": 25,26"unitPrice": 70000,27"rowTaxableAmount": 56000,28"name": "Haircut",29"variantName": "1 hour",30"fromLocationUuid": "4c03eec0-183c-11e7-a3f8-037fdcd360ec",31"toLocationUuid": "4c03eec0-183c-11e7-a15a-cda93ab15db3",32"autoGenerated": false,33"id": "0",34"type": "PRODUCT",35"libraryProduct": true36}37],38"discounts": [],39"payments": [40{41"uuid": "592b82f2-3ee4-11eb-9f71-a3ad065a16fc",42"amount": 70000,43"type": "SWISH",44"attributes": {}45}46],47"receiptCopyAllowed": true,48"references": {49"checkoutUUID": "589c2de6-3ee4-11eb-9f71-a3ad065a16fc"50},51"created": "2020-12-15T14:46:43.592+0000",52"refunded": false,53"groupedVatAmounts": {54"25.0": 7000055},56"refund": false57}
In a refund, money is being exchanged as the result of a returned sale, and an amount is transferred from the seller back to the buyer. Refunds are represented by the same information model as for purchases, but with negative quantity. There are also specific refund-related flags and fields.
The following purchase attributes are associated with refunds:
amount
. This will be negative in case of a refund.refund
. Iftrue
the purchase is a refund.refunded
. Iftrue
purchase has been refunded.refundsPurchaseUUID1
. The ID of the purchase that was refunded.refundedByPurchaseUUIDs1
. List with IDs of purchases that refunded this particular one as UUIDs version 1.
1{2"purchases": [3{4"source": "POS",5"purchaseUUID": "1x6BTNcFQ-esnIMUSdX8mQ",6"amount": -10000,7"vatAmount": -1071,8"country": "SE",9"currency": "SEK",10"timestamp": "2021-01-13T21:34:22.069+0000",11"gpsCoordinates": {12...13},14"purchaseNumber": 33,15"globalPurchaseNumber": 33,16"userDisplayName": "John Eriksen",17"userId": 5428764,18"organizationId": 37295469,19"products": [20{21"quantity": "-1",22"productUuid": "c8037b10-5381-11eb-a35d-4df8c9434273",23"variantUuid": "f29e9da0-5381-11eb-b308-d53bdad1e1da",24"vatPercentage": 12,25"unitPrice": 10000,26"rowTaxableAmount": -8929,27"name": "T-shirt",28"description": "",29"variantName": "Small",30"fromLocationUuid": "ab4b8ca6-c4d0-11e9-9f2e-2f9f3e29738c",31"toLocationUuid": "ab4b8d0a-c4d0-11e9-a836-71d1917b51b2",32"type": "PRODUCT",33"libraryProduct": true34}35],36"discounts": [],37"payments": [38{39"uuid": "5fdf1688-56ab-4686-857f-4ada4361a205",40"amount": -10000,41"type": "IZETTLE_CASH",42"references": {43"refundsPayment": "eb0db2eb-0ab0-4650-bd9c-492ebbe36938"44},45"attributes": {46"handedAmount": -1000047}48}49],50"refundsPurchaseUUID": "an16nO_YSpOw_0XVXSEndA",51"receiptCopyAllowed": true,52"references": {53"checkoutUUID": "d51c834e-d507-41e5-ae9e-81164bd7fe9b"54},55"created": "2021-01-13T21:34:22.069+0000",56"refunded": false,57"purchaseUUID1": "d71e814c-d705-43e7-ac9c-831449d5fc99",58"refundsPurchaseUUID1": "6a7d7a9c-efd8-4a93-b0ff-45d55d212774",59"groupedVatAmounts": {60"12.0": -1000061},62"refund": true63},64{65"source": "POS",66"purchaseUUID": "an16nO_YSpOw_0XVXSEndA",67"amount": 20000,68"vatAmount": 2142,69"country": "SE",70"currency": "SEK",71"timestamp": "2021-01-13T21:34:10.968+0000",72"gpsCoordinates": {73...74},75"purchaseNumber": 32,76"globalPurchaseNumber": 32,77"userDisplayName": "John Eriksen",78"userId": 5428764,79"organizationId": 37295469,80"products": [81{82"quantity": "1",83"variantUuid": "f29e9da0-5381-11eb-b308-d53bdad1e1da",84"vatPercentage": 12,85"unitPrice": 10000,86"rowTaxableAmount": 8929,87"name": "T-shirt",88"description": "",89"variantName": "Small",90"type": "PRODUCT",91"libraryProduct": true92},93{94"quantity": "1",95"productUuid": "c8037b10-5381-11eb-a35d-4df8c9434273",96"variantUuid": "f29e9da0-5381-11eb-9178-f532eaf25a4b",97"vatPercentage": 12,98"unitPrice": 10000,99"rowTaxableAmount": 8929,100"name": "T-shirt",101"description": "",102"variantName": "Medium",103"type": "PRODUCT",104"libraryProduct": true105}106],107"discounts": [],108"payments": [109{110"uuid": "eb0db2eb-0ab0-4650-bd9c-492ebbe36938",111"amount": 20000,112"type": "IZETTLE_CASH",113"attributes": {114"handedAmount": 20000115}116}117],118"refundedByPurchaseUUIDs": [119"1x6BTNcFQ-esnIMUSdX8mQ"120],121"receiptCopyAllowed": true,122"references": {123"checkoutUUID": "6b7c7b9d-eed9-4b92-b1fe-44d45c202675"124},125"created": "2021-01-13T21:34:10.968+0000",126"refunded": true,127"purchaseUUID1": "6a7d7a9c-efd8-4a93-b0ff-45d55d212774",128"refundedByPurchaseUUIDs1": [129"d71e814c-d705-43e7-ac9c-831449d5fc99"130],131"groupedVatAmounts": {132"12.0": 20000133},134"refund": false135}136],137"firstPurchaseHash": "16105736620691x6BTNcFQ-esnIMUSdX8mQ",138"lastPurchaseHash": "1610573650968an16nO_YSpOw_0XVXSEndA",139"linkUrls": [140"<https://purchase.izettle.com/purchases/v2?limit=2&descending=true&lastPurchaseHash=1610573650968an16nO_YSpOw_0XVXSEndA>; rel=\"next\""141]142}
See Purchase API reference for more details about parameters and attributes.
Parts of the purchase information are also consumed by other APIs, for example the Finance and Inventory APIs. See Purchase interactions.