Version: 2.10

Apps

Creating a new app

To create a new app, use the appCreate mutation. This mutation is only available to staff users with the MANAGE_APPS permission. Staff user can't grant app more permissions than he has for his own. The mutation takes the following input fields:

  • name: the name of the app.
  • isActive: whether to activate the app, defaults to true.
  • permissions: list of permissions the app should be granted.

Let's assume that we want to create an order processing service that can fetch and manage orders in Saleor. To do so, we create a new app with the MANAGE_ORDERS permission:

mutation {
appCreate(
input: { name: "Order processing service", permissions: [MANAGE_ORDERS] }
) {
authToken
app {
id
name
}
accountErrors {
field
code
}
}
}

If there are no errors in the response, a new app is created:

{
"data": {
"appCreate": {
"authToken": "Es1O0oB2O3PTeG9A4IVYUcaMoru3Ls",
"app": {
"id": "QXBwOjk=",
"name": "Order processing service"
},
"accountErrors": []
}
}
}

The response contains the authToken field - this is the token that the app needs to include in requests to Saleor API to authorize itself and have access to queries or mutations that it needs.

note

The authToken field is only available in the mutation response and cannot be fetched later, except for the last four digits.

App authentication

Saleor API for apps uses a bearer token. To avoid sending passwords with each request, you need to first create a token, and then include it as a header with every GraphQL request.

The authorization header for apps has the following format:

Authorization: Bearer <app-token>

Creating authorization keys

Creating an app with appCreate mutation creates the default authorization token (authToken). You can create more authorization keys with the appTokenCreate. The mutation takes the following fields:

  • app: ID of the app.
  • name: (optional) name of the key.
mutation {
appTokenCreate(
input: { app: "QXBwOjk=" }
) {
authToken
accountErrors {
field
code
}
appToken {
id
}
}
}

Revoking authorization keys

To revoke an authorization key, use the appTokenDelete:

mutation {
appTokenDelete(id: "QXBwOjk=") {
accountErrors {
field
code
}
}

Webhooks

Webhooks can be used to receive data from Saleor when particular events happen. The available events are:

NameDescription
ANY_EVENTSReceive webhooks when any of the available events is triggered (wildcard event).
CHECKOUT_QUANTITY_CHANGEDQuantity of a checkout line is changed.
CUSTOMER_CREATEDA new customer account is created.
ORDER_CREATEDA new order is placed.
ORDER_FULLY_PAIDPayment is made and an order is fully paid.
ORDER_UPDATEDAn order is updated; triggered for all changes related to an order; covers all other order webhooks, except for ORDER_CREATED.
ORDER_CANCELLEDAn order is cancelled.
ORDER_FULFILLEDAn order is fulfilled.
FULFILLMENT_CREATEDA new fulfillment is created.
PRODUCT_CREATEDA new product is created.

Webhooks' payloads are sent in POST requests.

Subscribing to a webhook

To subscribe to a webhook, we need to first create an app with proper permissions. Let's assume that we want to extend the order processing app that we've created in the example above. The app should receive notifications whenever new orders are created in Saleor. To do so, we'll create a new webhook using the webhookCreate mutation. The mutation takes the following input:

  • name: name of the webhook.
  • targetUrl: URL of a service that will receive webhooks requests.
  • events: list of the events to subscribe to.
  • app: ID of the app to which the webhook belongs.
  • isActive: whether to activate the webhook.
mutation {
webhookCreate(
input: {
name: "New orders notification"
targetUrl: "https://order-processing-service.example.com"
events: [ORDER_CREATED]
app: "QXBwOjk="
isActive: true
}
) {
webhook {
id
}
webhookErrors {
field
code
}
}
}

If there are no errors in the response, the webhook is successfully created. From now on, whenever a new order is placed, payload with order data will be sent to your targetUrl.

Updating a webhook

To update a webhook (e.g. to deactivate it or change the permissions), use the webhookUpdate mutation. The mutation takes similar input fields as the webhookCreate mutation. The example below shows how to deactive a webhook:

mutation {
webhookUpdate(id: "V2ViaG9vazox", input: { isActive: false }) {
webhook {
isActive
}
webhookErrors {
field
code
}
}
}

Removing a webhook

To fully remove a webhook, use the webhookDelete mutation:

mutation {
webhookDelete(id: "V2ViaG9vazox") {
webhookErrors {
field
code
}
}
}