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:

Name	Description
ANY_EVENTS	Receive webhooks when any of the available events is triggered (wildcard event).
CHECKOUT_QUANTITY_CHANGED	Quantity of a checkout line is changed.
CUSTOMER_CREATED	A new customer account is created.
ORDER_CREATED	A new order is placed.
ORDER_FULLY_PAID	Payment is made and an order is fully paid.
ORDER_UPDATED	An order is updated; triggered for all changes related to an order; covers all other order webhooks, except for ORDER_CREATED.
ORDER_CANCELLED	An order is cancelled.
ORDER_FULFILLED	An order is fulfilled.
FULFILLMENT_CREATED	A new fulfillment is created.
PRODUCT_CREATED	A 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

}

}

}