Writing Apps for Saleor
#
Key Concepts#
ArchitectureSaleor Apps are separate applications that use GraphQL to talk to a Saleor server and that can receive webhooks with event notifications from Saleor.
#
AuthenticationUnlike regular users, Saleor Apps use a bearer token. The token is assigned at App installation time and needs to be stored in a secure manner.
The authorization header for Apps has the following format:
#
The App manifestThe App manifest is a JSON file that describes the application, including its name, version, required permissions, and how it handles the store's data.
Saleor expects the manifest to use the following format:
note
During an installation of third-party App, Saleor will try to send an authentication token to provided tokenTargetUrl
.
For more details, see installing an app.
#
PermissionsName | Description |
---|---|
MANAGE_STAFF | Access to staff users data |
MANAGE_APPS | Manage apps |
MANAGE_USERS | Access to customers data |
MANAGE_DISCOUNTS | Manage discounts |
MANAGE_PLUGINS | Manage plugins |
MANAGE_GIFT_CARD | Manage gift cards |
MANAGE_MENUS | Manage the structure of menus |
MANAGE_ORDERS | Access to orders data |
MANAGE_PAGES | Manage pages |
MANAGE_PRODUCTS | Manage products |
MANAGE_PRODUCT_TYPES_AND_ATTRIBUTES | Manage product types and attributes |
MANAGE_SHIPPING | Manage shipping |
MANAGE_SETTINGS | Manage shop settings |
MANAGE_TRANSLATIONS | Manage translations |
MANAGE_CHECKOUTS | Manage checkout |
#
WebhooksWebhooks 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_CREATED | A new checkout is created. |
CHECKOUT_UPDATED | A checkout is updated; triggered for all updates related to an checkout;. |
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. |
#
Webhook protocolsWebhooks support below protocols:
- HTTP(S)
- Google Cloud Pub/Sub
- AWS SQS
#
HTTP(S)Webhook payloads are sent in POST requests.
All webhooks with targetUrl
, where the scheme is HTTP(S) will use this protocol.
Saleor calculates the HMAC sha256 header - X-Saleor-Signature
based on secretKey
and the payload
#
Google Cloud Pub/SubAll webhooks where scheme is gcpubsub
will be treated as a Google Cloud Pub/Sub webhooks.
The structure of targetUrl
should be as below:
To proper use the Google Cloud Pub/Sub you need to set the GOOGLE_APPLICATION_CREDENTIALS
environment variable
#
AWS SQSAll webhooks where scheme is awssqs
will be treated as AWS SQS webhooks.
The structure of targetUrl
should be as below:
#
Type of Appslocal
: create a custom App instance, assign explicitly provided permissions. The app is fully manageable from dashboard. You can change assigned permissions, add webhooks, or authentication token.local
app can be useful for creating integration with some services which will parse the webhook payload.note
If you're building a single service dedicated only to your shop this solution will handle all your needs.
third-party
: install App in Saleor and proceed with all required steps to prepare the communication channel for App.
Installation is fully automated. Saleor uses a defined App manifest to gather all required information.
If there are no errors during the installation, App gets the possibility to attach to Saleor Dashboard over the iframe, communicate with Saleor over API and use webhooks to subscribe for the given events.note
If you're building an App that will be published in the marketplace, then this solution is dedicated to you.
#
Creating and installing Apps from the command lineSaleor provides commands that can be used to create/install an App from the command line.
#
Creating local AppsTo create a local App with explicitly provided permissions use the create_app
command.
Arguments:
<name>
: the name of the App, required.--permission <PERM>
: assign permissionPERM
to the App. This argument can be repeated to specify multiple permissions.--activate
: immediately activate the new App.--target-url <URL>
: URL to send the API auth token to once installation is complete. [Optional]
Example: The following command will create an App named "Order App" that can access users and orders:
If the target URL is provided, Saleor will POST the API auth token, in the same JSON format, to the provided URL:
If the target URL is not specified, the command will output an API auth token in the following format:
#
Installing third-party AppsTo install a third-party
App based on its manifest URL use the install_app
command.
Arguments:
<manifest URL>
: URL of the manifest file, required.--activate
: immediately activate the new App.
Example: The following command will download given manifest and install the app:
App installation is confirmed by sending an API token to the specified token target URL. To see workflow details check - install app workflow.
#
The GraphQL API#
Third-party Apps#
Installing an AppInstalling an App with appInstall
mutation creates an App based on its manifest URL.
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:
appName
: the name of the App, required.manifestUrl
: URL of the manifest file, required.permissions
: list of permissions the app should be granted.activateAfterInstallation
: immediately activate the new App. Default true.
The response of the mutation contains the appInstallation
which contains all information about installation process.
If there are no errors in the response, a new app installation process is created:
The chart below explains workflow of the installation process:
#
Schedule installation#
Install an App#
Retrieving ongoing installationsTo fetch all ongoing and failed installations, use the appsInstallations
query.
This query is only available to staff users with the MANAGE_APPS
permission.
The query returns list of AppInstallation
objects.
The query returns a similar response:
#
Retrying failed installationIf the appsInstallations
query returns App with failed status, there is a possibility to retry the installation process.
This mutation is only available to staff users with the MANAGE_APPS
permission.
Staff user can't retry app installation if app requires more permissions than he has for his own.
The appRetryInstall
mutation will run the installation process for a given app.
The mutation takes the following fields:
id
: the id of theAppInstallation
, required.activateAfterInstallation
: immediately activate the new App. Default true.
Example of retrying installation of app with id QXBwT25nb2luZ0luc3RhbGxhdGlvbjoy
:
#
Deleting failed installationIf the appsInstallations
query returns App with failed status, there is a possibility to delete failed installation.
This mutation is only available to staff users with the MANAGE_APPS
permission.
The appDeleteFailedInstallation
mutation will delete failed installation.
The mutation takes the following fields:
id
: the id of theAppInstallation
, required.
#
Local Apps#
Creating an AppTo 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 totrue
.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:
If there are no errors in the response, a new app is created:
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.
#
Creating authorization keysCreating 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.
#
Revoking authorization keysTo revoke an authorization key, use the appTokenDelete
:
#
Retrieving all AppsTo fetch list of all apps, use apps
query. This query is only available to staff users with the MANAGE_APPS
permission.
The query returns a similar response:
#
Activating an AppTo activate an app, use the appActivate
mutation. This mutation is only available to staff users with the MANAGE_APPS
permission.
Staff user can't activate app which has more permissions than he has for his own.
The mutation takes the following fields:
id
: the id of theApp
, required.
The query returns a similar response:
#
Deactivating an AppTo deactivate an app, use the appDeactivate
mutation. This mutation is only available to staff users with the MANAGE_APPS
permission.
Staff user can't deactivate an app which has more permissions than they have for their own.
note
Deactivating an app will disable all auth-tokens generated for an app. The app won't receive a webhook payload.
The mutation takes the following fields:
id
: the id of theApp
, required.
The query returns a similar response:
#
Subscribing to a webhookTo 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.
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 webhookTo 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:
#
Removing a webhookTo fully remove a webhook, use the webhookDelete
mutation: