Pusher API reference

The Pusher API publishes information to your service. This information is data related to products, purchases, inventory etc.

You can subscribe to specific events in the Pusher API, so that you don't need to poll for data related to the events. When these events occur, the Pusher API will publish information about the events to your service.

Examples of events:

  • PurchaseCreated is triggered when a purchase gets created.
  • ProductUpdated is triggered when product information gets updated in the product library. See the list of all supported events.

The Pusher API uses webhooks. Webhooks are HTTP callbacks that receive notification messages for events. To create a webhook, users configure a webhook listener and subscribe it to events. A webhook listener is a server that listens at a specific URL for incoming HTTP POST notification messages. The messages are triggered when events occur.

Base URL

https://pusher.izettle.com

OAuth Scope

You can create webhook subscriptions using an access token or API key that corresponds to an organization. To update, delete, or view a subscription, use the same access token or API key.

To create or update a subscription to an event, you will need to be authorised with the corresponding scope.

E.g. you will require the READ:PURCHASE scope if you want to subscribe to the PurchaseCreated event. See the list of scopes for supported events.

For more information on how to get authorisation for a particular scope, see OAuth API.

Create a subscription

Creates a webhook subscription to a specific event.

Once the subscription for an event gets created, the Pusher API will publish data on your service whenever that event occurs.

Example: You created a subscription for the ProductUpdated event. Whenever a product gets updated in the product library, the ProductUpdated event occurs. Then you will receive event data on the destination server that you have exposed publicly. The event data is a payload for the updated product. See the list of payloads for all events.

Note: The Pusher API will push data for an event only once. However, there may be cases where it gets published more than once. You don't need to save the data more than once.

1
POST /organizations/{organizationUuid}/subscriptions

See example Create a webhook subscription.

Parameters

Click to hide all request parameters for creating a subscription.
NameTypeInRequired/OptionalDescription
organizationUuidstringpathrequiredUnique identifier for your organisation. You can use following options to fill in this value:
  • Use self as the value. This will retrieve your organizationUuid from the authentication token in the request.
  • Get it by using the users/self endpoint of OAuth API. For more information, see OAuth API.
uuidstringqueryrequiredUnique identifier for the subscription as UUID version 1.
transportNamestringqueryrequiredThe message option used by Pusher API. Currently only WEBHOOK is supported.
eventNamesarrayqueryrequiredEvent names for events that you want to create subscription for. The events are specified in an array.
If you pass an empty array, you will subscribe to all events that the Pusher API supports. In this case, make sure that you have all the corresponding authorisation scopes issued. See the list of scopes.
destinationstringqueryrequiredYour service URL publicly exposed where the Pusher API will publish messages for subscribed events.
contactEmailstringqueryrequiredThe email address used to notify in case of any errors in subscription or the destination.
The email must be a valid email address and should not exceed 512 characters.

Responses

Click to hide HTTP status codes.
Status codeDescription
200 OKReturned when a subscription is successfully created.
401 UnauthorizedReturned when one of the following occurs:
  • The authentication information is missing in the request.
  • The authentication token has expired.
  • The authentication token is invalid.
403 ForbiddenReturned when the scope being used in the request is incorrect.
E.g. If you provide a permission scope of READ:PRODUCT while creating a subscription for PurchaseCreated then the Pusher API will return 403 in the response.
400 Bad RequestReturned when one of the following occurs:
  • The transportName or uuid is missing in the request.
  • A subscription with the uuid passed in request already exists.
  • The destination is not accessible.
422 Unprocessable EntityReturned when one of the following occurs:
  • The destination or contactEmail is missing in the request.
  • The contactEmail has an invalid value for email address.
500 Internal Server ErrorReturned when one of the following occurs:
  • The destination responded with a non-successful HTTP response code.
  • The Pusher API encountered an internal server error.
Click to hide response attributes.

A successful 200 OK response will have the following attributes:

NameTypeDescription
uuidstringUnique identifier for the created subscription as UUID version 1.
transportNamestringThe message option used by Pusher API. Currently only WEBHOOK is supported.
eventNamesarrayThe event names for the created subscription.
updatedstringThe timestamp (in UTC) when the subscription was last updated.
destinationstringThe public URL exposed by you where the Pusher API will publish messages for subscribed events.
contactEmailstringThe email used to notify any errors for subscriptions or the destination.
statusstringThe status of the created subscription.
signingKeystringThe key used to verify that all incoming webhook messages from the Pusher API originate from Zettle.

Get all subscriptions

Gets all the webhook subscriptions for an organisation.

1
GET /organizations/{organizationUuid}/subscriptions

See example Get webhook subscriptions.

Parameters

Click to hide all request parameters for getting all subscriptions.
NameTypeInRequired/OptionalDescription
organizationUuidstringpathrequiredUnique identifier for your organisation. You can use following options to fill in this value:
  • Use self as the value. This will retrieve your organizationUuid from the authentication token in the request.
  • Get it by using the users/self endpoint of OAuth API. For more information, see OAuth API.

Responses

Click to hide HTTP status codes.
Status codeDescription
200 OKReturned when the Pusher API returns a collection of subscriptions for the client.
401 UnauthorizedReturned when one of the following occurs:
  • The authentication information is missing in the request.
  • The authentication token has expired.
  • The authentication token is invalid.
500 Internal Server ErrorReturned when the Pusher API encounters an internal server error.
Click to hide response attributes.

A successful 200 OK response will return an array of subscriptions. Each subscription contains the following response attributes:

NameTypeDescription
uuidstringUnique identifier for the created subscription as UUID version 1.
transportNamestringThe message option used by Pusher API. Currently only WEBHOOK is supported.
eventNamesarrayAll the events for the created subscription.
updatedstringThe timestamp (in UTC) when the subscription was last updated.
destinationstringThe destination URL where the Pusher API will push messages for subscribed events.
contactEmailstringThe email used to notify any errors for subscriptions or the destination.
statusstringThe status of the created subscription.
signingKeystringThe key used to verify that all incoming messages from the Pusher API originate from Zettle.

Update a subscription

Updates an existing webhook subscription.

1
PUT /organizations/{organizationUuid}/subscriptions/{subscriptionUuid}

See example Update a webhook subscription.

Parameters

Click to hide all request parameters for updating a subscription.
NameTypeInRequired/OptionalDescription
organizationUuidstringpathrequiredUnique identifier for your organisation. You can use following options to fill in this value:
  • Use self as the value. This will retrieve your organizationUuid from the authentication token in the request.
  • Get it by using the users/self endpoint of OAuth API. For more information, see OAuth API.
subscriptionUuidstringpathrequiredUnique identifier for an existing subscription as UUID version 1.
transportNamestringqueryoptionalThe message option used by the Pusher API. E.g. WEBHOOK. You need to specify the same option that you used while creating the subscription.
eventNamesarrayqueryoptionalEvents that you want to update on the existing subscription. The events are specified in an array.
destinationstringqueryoptionalThe destination URL where the Pusher API will push data for the updated subscription.
contactEmailstringqueryoptionalThe email address used to notify in case of any errors in subscription or the destination.
The email must be a valid email address and should not exceed 512 characters.

Responses

Click to hide HTTP status codes.
Status codeDescription
200 OKReturned when the Pusher API updates the subscription successfully.
401 UnauthorizedReturned when one of the following occurs:
  • The authentication information is missing in the request.
  • The authentication token has expired.
  • The authentication token is invalid.
404 Not FoundReturned when the subscription to be updated does not exist or cannot be found.
405 Method Not AllowedReturned when the subscriptionUuid is missing in the request.
400 Bad RequestReturned when the eventNames parameter contains events that are not supported by the Pusher API.
422 Unprocessable EntityReturned when one of the following occurs:
  • Returned if the destination specified in the request is empty.
  • The destination value is not a valid HTTPS URL.
500 Internal Server ErrorReturned when the Pusher API encounters an internal server error. In case this error persists, contact our developer support.
Click to hide response attributes.

The Pusher API returns a 200 OK response without any content.

Delete a subscription

Deletes an existing webhook subscription.

1
DELETE /organizations/{organizationUuid}/subscriptions/{subscriptionUuid}

See example Delete a webhook subscription.

Parameters

Click to hide all request parameters for deleting a subscription.
NameTypeInRequired/OptionalDescription
organizationUuidstringpathrequiredUnique identifier for your organisation. You can use following options to fill in this value:
  • Use self as the value. This will retrieve your organizationUuid from the authentication token in the request.
  • Get it by using the users/self endpoint of OAuth API. For more information, see OAuth API.
subscriptionUuidstringpathrequiredUnique identifier for an existing subscription as UUID version 1.

Responses

Click to hide HTTP status codes.
Status codeDescription
204 No ContentReturned when the Pusher API deletes the subscription successfully.
401 UnauthorizedReturned when one of the following occurs:
  • The authentication information is missing in the request.
  • The authentication token has expired.
  • The authentication token is invalid.
404 Not FoundReturned when one of the following occurs:
  • The subscriptionUuid is missing in the request.
  • A subscription was not found for the subscriptionUuid passed in the request
500 Internal Server ErrorReturned when the Pusher API encounters an internal server error.
Click to hide response attributes.

The Pusher API returns a 204 No Content response without any content.

Supported events

Click to hide a list all the events supported by the Pusher API and their corresponding authorization scopes.
Event nameRequired scopeTrigger
PurchaseCreatedREAD:PURCHASEA purchase is finalized and a receipt is created.
OrganizationUpdatedREAD:USERINFOA property of an organization is updated. E.g. name, email address etc.
ProductCreatedREAD:PRODUCTA product gets created in the product library.
ProductUpdatedREAD:PRODUCTA product gets updated in the product library.
ProductDeletedREAD:PRODUCTA product gets deleted in the product library.
InventoryBalanceChangedREAD:PRODUCTEither:
  • A sale is made for a product and purchase gets created. This leads to change in the balance of the product in the inventory.
  • The stock of a product gets updated in the product library.
InventoryTrackingStartedREAD:PRODUCTInventory tracking for a product is enabled in the Zettle Go app.
InventoryTrackingStoppedREAD:PRODUCTInventory tracking for a product is disabled in the Zettle Go app.
ApplicationConnectionRemovedany scopeThe application was disconnected from Zettle organization and the OAuth refresh token has been invalidated.
PersonalAssertionDeletedany scopeThe API key used to create subscriptions is deleted.

Examples

Create a webhook subscription

Request

1
POST /organizations/{organizationUuid}/subscriptions
1
{
2
"uuid": "f02f80f8-8f35-11eb-8dcd-0242ac130003",
3
"transportName": "WEBHOOK",
4
"eventNames": ["ProductUpdated"],
5
"destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
6
"contactEmail": "your_email@domain.com"
7
}

Response

1
{
2
"uuid": "f02f80f8-8f35-11eb-8dcd-0242ac130003",
3
"transportName": "WEBHOOK",
4
"eventNames": ["ProductUpdated"],
5
"updated": "2021-03-29T16:31:47.087507Z",
6
"destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
7
"contactEmail": "your_email@domain.com",
8
"status": "ACTIVE",
9
"signingKey": "zLzClQLQN8yfH8aEjONeXzgJRAHR0zpD7RonFCpizujCUCectBlln0vFArTbLPYa"
10
}

Get webhook subscriptions

Request

1
GET /organizations/self/subscriptions

Response

1
[
2
{
3
"uuid": "f02f80f8-8f35-11eb-8dcd-0242ac130003",
4
"transportName": "WEBHOOK",
5
"eventNames": ["ProductUpdated"],
6
"updated": "2021-03-30T07:48:52.228Z",
7
"destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
8
"contactEmail": "your_email@domain.com",
9
"status": "ACTIVE",
10
"signingKey": "U0Ani1WTTwwbjUnHlQAEDCRXQoQn9z9e4q55UUTyeZJt89z9XXN5ssd4Cgh0evJa"
11
},
12
{
13
"uuid": "6eefcb26-912c-11eb-a8b3-0242ac130003",
14
"transportName": "WEBHOOK",
15
"eventNames": ["ProductDeleted"],
16
"updated": "2021-03-30T07:49:35.294Z",
17
"destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
18
"contactEmail": "your_email@domain.com",
19
"status": "ACTIVE",
20
"signingKey": "PSjClzC2HNEZZoFU7aaF9DSmn9WJBXLfEIAkbBq15lNknnijPT2AKEsvf2YHPrsQ"
21
},
22
{
23
"uuid": "7c9e43ce-912c-11eb-a8b3-0242ac130003",
24
"transportName": "WEBHOOK",
25
"eventNames": ["InventoryBalanceChanged", "ProductCreated"],
26
"updated": "2021-03-30T07:50:13.489Z",
27
"destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
28
"contactEmail": "your_email@domain.com",
29
"status": "ACTIVE",
30
"signingKey": "H2XDdE5REqT55rDTvAPqpA8UDY4mO3QSmcLO7h0PxvJ4qETKfx9rfzVxuKplUOYz"
31
},
32
{
33
"uuid": "08db4d6e-912d-11eb-a8b3-0242ac130003",
34
"transportName": "WEBHOOK",
35
"eventNames": ["InventoryBalanceChanged", "ProductCreated"],
36
"updated": "2021-03-30T07:54:11.798Z",
37
"destination": "https://webhook.site/f62e2311-1232-4d8f-b75e-80e9ce013dd4",
38
"contactEmail": "your_email@domain.com",
39
"status": "ACTIVE",
40
"signingKey": "s4T28XWVGBl8us8fvRxmY4HnFQgTbMiFtqniXpWrAIx0rv5YN7RFAygyjWSg7Nip"
41
}
42
]

Update a webhook subscription

Request

1
PUT /organizations/self/subscriptions/df209936-8f31-11eb-8dcd-0242ac130003
1
{
2
"eventNames": ["ProductUpdated", "CardPaymentInvalid"]
3
}

Response

1
200 OK

Delete a webhook subscription

Request

1
DELETE /organizations/self/subscriptions/uuid/f02f80f8-8f35-11eb-8dcd-0242ac130003