Purchase API reference

The Purchase API provides read only information about purchases made through Zettle. A purchase represents a receipt, it's immutable and contains information about sold items. The purchase information includes one or several payments received, taxes, discounts and so on. Refunds are represented by the same model, but with negative quantity and refund-related flags/fields.

Base URL

https://purchase.izettle.com

OAuth scope

  • READ:PURCHASE

Fetch a list of purchases

Returns a list of purchases for a merchant. Purchases up to three years old are available for fetching.

1
GET /purchases/v2

Parameters

Click to hide request parameters.
NameTypeInRequired/OptionalDescription
lastPurchaseHashstringqueryoptionalA value from "lastPurchaseHash" from the result of a previous request to retrieve next page of purchases.
startDatestringqueryoptionalThe start date UTC(inclusive) for purchases to be retrieved from until today or endDate if provided. For example "2020-01-01", "2020-01-01T17:00". By default startDate is resolved to three years back.
endDatestringqueryoptionalThe last date UTC(exclusive) until which the purchases will be retrieved. For example 2021-01-13, 2021-01-13T12:30.
limitintegerqueryoptionalThe maximum number of records to return. Value range 1–1000.
descendingbooleanqueryoptionalWhen set to true, most recent purchases are returned first. Defaults to false if not specified.

Responses

Click to hide response codes.
HTTP Status codeDescription
200 OKSuccessful.
401 UnauthorizedYou were not authorized to execute this operation.
429 Too Many RequestsYou hit the rate limit. Retry request later.
Click to hide response attributes.
NameTypeDescription
purchasesarrayList of purchases. See Fetch a purchase for more information.
firstPurchaseHashstringReference to the first purchase in the list returned.
lastPurchaseHashstringReference to the last purchase in the list returned. Use it as parameter for the next page with purchases.
linkUrlsarrayList of links to pages. Example:
"linkUrls": ["https://purchase.izettle.com/purchases/v2?limit=4&startDate=2021-01-01T00%3A00%3A00.000Z&descending=true&lastPurchaseHash=1610019370783OWXebOK1QKmwcwSyhCQkzA"]

Fetch a purchase

Returns a purchase with a given UUID.

1
GET /purchases/v2/{purchaseUuid}

Parameters

Click to hide request parameters.
NameTypeInRequired/OptionalDescription
purchaseUuidstringpathrequiredUnique ID of the purchase as UUID within the Zettle system.

Responses

Click to hide response codes.
HTTP Status codeDescription
200 OKSuccessful.
401 UnauthorizedYou were not authorized to execute this operation.
404 Not foundPurchase with given UUID not found.
429 Too Many RequestsYou hit the rate limit. Retry request later.
Click to hide response attributes.

Table 1. Purchase attributes

NameTypeDescription
sourcestringSource of purchase, value can be one of the following: - "POS" - purchase made with Zettle Go app - "WEB_SHOP" - purchase made online - "SDK" - purchase made through SDK
purchaseUUIDstringUnique ID of a purchase. Deprecated.
purchaseUUID1stringUnique ID of a purchase as UUID version 1.
timestamparrayCreated timestamp according to the ISO 8601 format. For example "2019-12-03T17:05:06.123+0000".
purchaseNumberintegerIncremental receipt number.
globalPurchaseNumberintegerIncremental receipt number, only different from purchaseNumber if several cash registers are used by the merchant.
amountintegerGross amount (inc VAT) in minor currency units. For example €9.95 EUR, amount will be 995. Is negative in case of refund.
vatAmountintegerVAT amount for the whole purchase in minor currency units. For example €5 EUR, amount will be 500.
countrystringTwo-letter country code for country the merchant operates in. Examples "SE", "NO", "GB", "FR", "DE", "DK".
currencystringThree-letter currency code according to ISO 4217. Examples "SEK", "NOK", "EUR", "DKK".
productsarrayList of items that were sold. See section Product attributes for more information.
paymentsarrayPayments that were processed/received. See section Payment attributes for more information.
discountsobjectDiscounts applied on the whole purchase. See Discounts for more information.

Example:

1
"discounts": [
2
{
3
"name": "4 for £12",
4
"amount": 200,
5
"quantity": 1,
6
"value": 200
7
}
8
]

OR

1
"discounts": [
2
{
3
"name": "Staff",
4
"percentage": 50,
5
"quantity": 1,
6
"value": 2000
7
}
8
]

name attribute is optional, not always present. For more information see Discounts.

serviceChargeobjectService charge added to a purchase, for example delivery charge.

Example:

1
"serviceCharge": {
2
"amount": 499,
3
"title": "Standard Shipping",
4
"vatPercentage": 16.0,
5
"quantity": "1"
6
}
createdstringCreated timestamp according to the ISO 8601 format. For example "2019-12-03T17:05:06.123+0000".
refundbooleanIndicates if given purchase is a refund. See Refunds for more information.
refundedbooleanIndicates if given purchase has been refunded. See Refunds for more information.
refundsPurchaseUUIDstringUnique ID of the purchase that was refunded as string. Deprecated.
refundsPurchaseUUID1stringUnique ID of the purchase that was refunded as UUID version 1. See Refunds for more information.
refundedByPurchaseUUIDsarrayList with IDs of purchases that refunded this particular one. Deprecated.
refundedByPurchaseUUIDs1arrayList with IDs of purchases that refunded this particular one as UUIDs version 1. See Refunds for more information.
1
{
2
"refundedByPurchaseUUIDs1": [
3
"3d221367-1c92-498d-9e94-ef5cc4f45d61",
4
"e37d63c2-97af-4bec-b6ac-1cf212f97d90"
5
]
6
}
groupedVatAmountsarrayContains VAT amounts grouped by percentage.

Example:

1
"groupedVatAmounts": {
2
"25.0": 70000,
3
"12.0": 5000
4
}
userDisplayNamearrayName of the merchant/employee that took the payment.
gpsCoordinatesobjectContains GPS coordinates of the location where purchase was made.

Example:

1
"gpsCoordinates": {
2
"longitude": 19.80452501310729,
3
"latitude": 66.609375,
4
"accuracyMeters": 165
5
}
cashRegisterarrayFor internal use. There is no public API available for cash register.

Note: More attributes can potentially be added. Make sure your integration is built in a tolerant way.

Table 2. Product attributes

NameTypeDescription
quantitystringQuantity of items. Can be a whole number or a decimal number, and negative in case of refund.
typestring

Describes the type of item that was purchased. Enumeration values:

  • "PRODUCT" - Indicates that the item sold was predefined in product library.
  • "CUSTOM_AMOUNT" - Indicates that the item sold was a custom amount entered in the app at the time of purchase.
  • "GIFTCARD" - Indicates that the item sold was a gift card.
detailsobjectMay contain information related to the specific type, for example item lines of type GIFTCARD will have a giftcardUuid attribute pointing out what gift card that was sold/returned as part of purchases.

Example:

1
"details": {
2
"giftcardUuid": "290371f0-a8a5-11e5-b862-d6cb9f787e88"
3
}

Gift card details can be fetched through Gift Card API.

productUuidstringUnique ID of product in product library as UUID.
namestringName of the product sold.
variantUuidstringUnique ID of variant in product library as UUID.
variantNamestringName of variant.
vatPercentagenumberVAT percentage of the item.
rowTaxableAmountnumberAmount on which VAT is chargeable in minor currency units. For example £12.5 GBP will be 1250.
unitPricenumberUnit price of the item in minor currency units. For example €10 EUR will be 1000.
unitNamestringName of unit, for example "kg", "hour".
commentstringComment for the item row.
discountobjectDiscount for the item row.

Example:

1
"discount": {
2
"percentage": 20,
3
"quantity": 1
4
}
5
6
OR
7
8
"discount": {
9
"amount": 1000,
10
"quantity": 1
11
}

See Discounts for more information.

discountValueintegerDiscount amount in minor currency units. For example €5 EUR will be 500.
libraryProductbooleanIndicates if product registered in merchant’s product library.
skustringSKU of product in inventory.
barcodestringBarcode of the product in inventory.
fromLocationUuidstringSupplier location ID as UUID (inventory context).
toLocationUuidstringStore location ID as UUID (inventory context).

Table 3. Payment attributes

NameTypeDescription
uuidstringUnique ID of the payment as UUID. Can be linked to transactions in Finance API.
typestringPayment type used when making a purchase. See Payment types for more information.
gratuityAmountintegerCorresponds to the tipping amount in the purchase. This feature is not available in all supported by Zettle countries. When the gratuityAmount is set, the payment amount will include the gratuity amount.
referencesobjectOther references. Example:
1
{
2
"references": {
3
"refundsPayment": "4647cd58-ebc6-4ef8-9572-559811c90b11"
4
// UUID of original payment that was refunded or partially refunded.
5
}
6
}
attributesobjectAdditional information about the payment. Different attributes are included depending on payment type.

Table 4. Payment types

Payment typeDescription
IZETTLE_CARD

Payment taken with Zettle card reader.

Example:

1
{
2
"uuid": "165b88a0-07a3-11e6-9dae-43c30f1bff5b",
3
"amount": 2000,
4
"gratuityAmount": 0,
5
"type": "IZETTLE_CARD",
6
"attributes": {
7
"cardHolderVerificationMethod": "None",
8
"maskedPan": "535583******0000",
9
"cardPaymentEntryMode": "CONTACTLESS_EMV",
10
"referenceNumber": "B6MFKZTMKP",
11
"authorizationCode": "429579",
12
"cardType": "MASTERCARD",
13
"terminalVerificationResults": "0000008001",
14
"applicationIdentifier": "A0000000041010",
15
"applicationName": "Debit MasterCard"
16
}
17
}
IZETTLE_CARD_ONLINE

Payment taken with Zettle online, for example with payment link.

Example:

1
{
2
"uuid": "3d38a2b4-3a02-11eb-bdbf-9f47e7b17f57",
3
"amount": 18145,
4
"type": "IZETTLE_CARD_ONLINE",
5
"attributes": {
6
"cardType": "MASTERCARD",
7
"maskedPan": "517036******000",
8
"cardPaymentEntryMode": "ECOMMERCE",
9
"referenceNumber": "PKDBOSWWWW",
10
"paymentlinkOrderUuid": "bb6d3b38-3a01-11eb-970c-e3b88c945415"
11
}
12
}
IZETTLE_CASHCash payment registered with Zettle.

Example:

1
{
2
"uuid": "ec138d2e-8e29-41c0-a4c4-17b2b4ab7f8b",
3
"amount": 2000,
4
"type": "IZETTLE_CASH",
5
"attributes": {
6
"changeAmount": 3000,
7
"handedAmount": 5000
8
}
9
}
IZETTLE_INVOICEZettle invoice is issued for a purchase with this payment type.

Example:

1
{
2
"amount": 92250,
3
"attributes": {
4
"orderUUID": "52201c9a-1234-11eb-9909-5960351f9426",
5
"invoiceNr": "iz18",
6
"dueDate": "2020-10-29"
7
},
8
"type": "IZETTLE_INVOICE",
9
"uuid": "52372638-1223-11eb-85a4-e6977798fc1e"
10
}
SWISHAlternative payment method available in Sweden, has no additional attributes.
VIPPSAlternative payment method available in Norway, has no additional attributes.
MOBILE_PAYAlternative payment method available in Denmark, has no additional attributes.
PAYPALPayment made with PayPal wallet.

Example:

1
{
2
"uuid": "74d528f1-1bd1-11ed-afd0-27740sse6511",
3
"amount": 1200,
4
"type": "PAYPAL",
5
"attributes": {
6
"paypalId": "5TW66818TP9560FFF"
7
}
8
}
STORE_CREDITStore credit is usually a document offered by a store to a customer who returns an item not eligible for a refund. It can also be offered when a customer doesn’t want to get chargeback on the credit card that was used. Furthermore, it can be used to buy other goods at the same store.
GIFTCARDPayment made with a gift card(certificate/voucher) issued by the merchant.
KLARNAPayment made with Klarna.

Example:

1
{
2
"uuid": "fab90e28-c666-4f60-a96b-1515deb88300",
3
"receiverOrganization": "59ef0f5a-5416-11eb-ae93-0242ac130002",
4
"amount": 180319,
5
"type": "KLARNA",
6
"currency": "SEK",
7
"country": "SE",
8
"referenceNumber": "6B2MFVVDXXX",
9
"references": {
10
"checkoutUUID": "3431ad48-3ba4-11eb-bc4c-f3c0af76e000"
11
},
12
"commission": {
13
"totalAmount": 5621,
14
"vatAmount": 0,
15
"vatRate": 17.0,
16
"modelId": "4656dbf8-5161-11e9-b86f-74970dafc264",
17
"model": {
18
"fixed": 590,
19
"percentage": 2.79
20
}
21
},
22
"createdAt": "2020-12-11T11:32:14.000+0000",
23
"details": {
24
"klarnaOrderId": "f7abd5be-04bd-1565-b557-df865f5ba7a0",
25
"klarnaProduct": "PAY_LATER",
26
"klarnaReference": "029TN5TTT",
27
"acquiringChannel": "IN_STORE"
28
},
29
"attributes": {}
30
}