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.

Using the API

Authorisation

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.

What is a purchase?

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.

Purchase information

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.

1
GET  /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": 165
14
    },
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": true
36
        }
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": 70000
55
    },
56
    "refund": false
57
}

Refunds

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. If true the purchase is a refund.
  • refunded. If true 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": true
34
                }
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": -10000
47
                    }
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": -10000
61
            },
62
            "refund": true
63
        },
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": true
92
                },
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": true
105
                }
106
            ],
107
            "discounts": [],
108
            "payments": [
109
                {
110
                    "uuid": "eb0db2eb-0ab0-4650-bd9c-492ebbe36938",
111
                    "amount": 20000,
112
                    "type": "IZETTLE_CASH",
113
                    "attributes": {
114
                        "handedAmount": 20000
115
                    }
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": 20000
133
            },
134
            "refund": false
135
        }
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.

Purchase information usage

Parts of the purchase information are also consumed by other APIs, for example the Finance and Inventory APIs. See Purchase interactions.

Related information