Product library concept

The Product Library service provides information about a merchant’s products. Using the Product Library API, you can build product libraries and manage products through code. You can also build integrations with other third-party applications and services, for example to synchronize product data between physical and on-line stores.

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. Depending on the type of app and integration you are building, this can be done in different ways. See OAuth API.

What is a product library?

The product library service holds data about a merchant´s product offerings. The data contains products for sale, and related information such as variants, categories, discounts, and taxes. The product library is a representation of all items that can be displayed, put in a shopping cart, and sold to a customer. Items can be either products or discounts.

A product is a synthetic construct, wrapping one or more variants, which is the actual item being sold (SKU). Variants expresses different variations of properties, for example the size, color, or price.

A discount reduces the total amount charged in a shopping cart. It can be used per line item, or on the whole cart. It may reduce the affected amount by a percentage, or by a fixed amount.

The entire product library can be fetched through the library endpoint, where each consecutive change applied to the library is available. Once the full library is retrieved, only later events needs to be fetched, to keep the client application up-to-date with the server.

About the Product Library API

Using the Product Library API you can programmatically manage a products in a merchant´s product library. Through the API, you can create, update, and delete product library items. You can manage items individually, or process multiple items in one API call. Depending on how products are retrieved, pagination is supported to help reduce the server load. See Fetch products.

Product library events

Using the Zettle Pusher API, your application can get notified about changes in the product library. You can create a webhook subscribing to product library-related events. When the event occurs, a notification is sent to the specified notification URL. The notification is a POST request with event details in JSON format.

The following events are available for the product library:

  • ProductCreated. A product is added to the product library from Zettle POS or the app.
  • ProductUpdated. Information for a product has been changed, from Zettle POS or the app.
  • ProductDeleted. A product is removed from the product library from Zettle POS or the app.

You can for example create a subscription for the ProductUpdate event. Whenever a product gets updated in the product library, the ProductUpdate event occurs, and your application will receive event data on the destination server. The event data is the payload for the updated product.

See Pusher API for more details.

Managing product images

When using the Product Library API to manage product libraries, you can upload one or more product images using the Image API. After uploading, the Image API returns an imageUrl that can be added to a product using the Product Library API.

See Product library data for more details.

Recommendations and limits

The following lists some recommendations and limits to ensure optimal performance for your product library integration.

  • Product library size. It´s recommneded to keep the number of items in the Product Library below 10,000.
  • API call rates. When constructing API calls, it´s recommended to not exceed 150 requests/10 seconds.
  • Number of variants for a product. You can only assign up to 99 variants to a product. See Product library data for details.
  • Product and variant UUID. In a product library, every product and product variant must have a unique UUID. For more information, see Product library data.