Purchase API interactions
The Purchase API provides read-only information about purchases made through Zettle. This information is then available
for consumption by other services. Updates on accounts, gift cards, and inventory are examples of instances that use the
purchase information. The purchase information can be received by subscribing to specific events using Pusher API.
See Pusher API overview for more
details.

Merchants who take payments with Zettle have a Zettle account that processes transactions for payments. The account
handles different status of transactions. After a merchant takes a payment with Zettle, the payment transaction is
recorded and confirmed, and the payout is prepared. The payment happens before the actual purchase, most often
immediately. However, due to different reasons, some delay might occur between the two.
The following describes how purchase information is used by other instances.
See Purchase concept and Purchase API reference for specific details
about the purchase information.
The Finance API is used for fetching finance-related information processed through Zettle. The information includes
account balance, transactions processed through Zettle, and payout. This also includes payment types which are part of
the Purchase API information, whereas transactions represent the Finance API side.
In the Purchase API, payments include the payment type and the payment UUID, which are used by the Finance API to link
to a transaction.
The Finance API records transactions from payment types in the Purchase API. For example, every purchase made with a
card is displayed as
IZETTLE_CARD
in the Purchase API, and CARD_PAYMENT
and CARD_PAYMENT_FEE
in the Finance API.
They are linked through the originatingTransactionUuiD
(Finance API), and the payment UUID (Purchase API).The following payment types are available in the Purchase API:
IZETTLE_CARD
IZETTLE_CARD_ONLINE
IZETTLE_CASH
IZETTLE_INVOICE
MOBILE_PAY
SWISH
VIPPS
GIFTCARD
PAYPAL
KLARNA
Not all of these payment types are supported by the Finance API.
IZETTLE_CARD
(payment/refund), IZETTLE_CARD_ONLINE
, PAYPAL
, and KLARNA
are supported, and can be linked to transaction types.See Fetch purchase information for card transactions for more information.
For refunds,
IZETTLE_CARD
is the paymen t type used in the Purchase API, and CARD_REFUND
and CARD_PAYMENT_FEE_REFUND
are the corresponding transaction types in the Finance API. In the refund case, there will
be a new purchase entry created with a negative amount. In the Finance API, CARD_REFUND
will be referring to the new
purchase, instead of the original one.Some payment types in the Purchase API involve transaction of funds that do not go through Zettle:
IZETTLE_CASH
, SWISH
, VIPPS
, MOBILE_PAY
, and GIFTCARD
. These transactions will not show up in the Finance
API.Linking of the
IZETTLE_INVOICE
payment type to transactions in the Finance API depends on how the invoice is paid. A
merchant can issue an invoice, but it doesn't guarantee that the buyer will pay it through the payment option provided
by Zettle. For example, a merchant can issue the invoice to the buyer. The buyer can then use a payment method like
Swish or cash, to pay the invoice.In Sweden for example, buyers get the option to pay a Zettle invoice through bank transfer. In this case, the payment
will be dispersed to the merchant through an
INVOICE_PAYMENT
transaction in the Finance API. It is currently not
possible to map an INVOICE_PAYMENT
in the Finance API with a purchase.In countries where invoices can not be paid with bank transfer, buyers will have the option to pay online with a card.
If the invoice is paid this way, it will be dispersed to the merchant as
IZETTLE_CARD
or IZETTLE_CARD_ONLINE
in the
Purchase API, and CARD_PAYMENT
in the Finance API, instead of an INVOICE_PAYMENT
.A gift card can be used to pay for a purchase, partially or entirely. A gift card can also be a product in the product
library, and sold in the POS system. The Gift Card API provides extra information about purchases made through Zettle
using gift cards.
- The
GIFTCARD
payment type represents a payment made with a gift card (certificate/voucher) issued by a merchant. - In the Purchase API response, the product attribute
type
is an enumeration which has aGIFTCARD
value indicating that a product is a gift card.
See Gift Card API for more details.
When a product is sold, it is moved from the
STORE
location to the SOLD
location. The information in the Purchase
API contains details about location movements through the fromLocationUuid
and toLocationUuuid
parameters, for the
product sold.Examples:
For Finance API interactions, you can monitor purchases by subscribing to the
PurchaseCreated
event.To monitor inventory balance updates, you can subscribe to the
InventoryBalanceChanged
event.See Pusher API overview for more
details.