Skip to main content

Upgrading From 2.11 To 3.0

Preparation

The new version introduces many new features as well as some breaking changes. As a result, most API clients such as Saleor Apps and storefronts will require changes.

Before you start the process, create a backup of your data. Also, let your Celery worker process the task queue before starting API migration.

Due to the scope of the upgrade, downtime will be required.

Multichannel

Existing data will be assigned to the default-channel created during the database migration. As long as the shop has only one channel defined, you are not required to specify the channel argument. Thanks to that, you'll be able to migrate the storefront to 3.0 gradually.

After adding more channels, the channel argument will become required. Because of that, we recommend always adding the channel argument, even if you have only one channel:

{
products(first: 5, channel: "default-channel") {
edges {
node {
id
name
description
}
}
}
}

Besides the impact on fetching the data, you'll be required to specify the channels during the checkout creation process. Read more at the Checkout page.

If you use the API to modify objects (for example, with an external app), please note that channel-depending fields have dedicated mutations. Updating product price requires using the productChannelListingUpdate mutation.

Object attributes that can be defined on a channel basis can be referenced.

Email templates

The email templates are stored in the database instead of static server files in the new email implementation. This change enables editing the templates in the dashboard and adds the integration with Sendgrid. If you modified the default email templates provided by Saleor, you need to migrate them to the Handlebars format and configure them in the dashboard.

Read more about user and admin email plugins here:

Editor.js rich text editor and description fields

All rich text fields now use Editor.js instead of Draft.js. Our database migration should convert the old format to the new one, but visual inspection is recommended.

To render rich text in your storefront, you can use Editor.js in the read-only mode, or use one of the libraries recommended by its authors.

Additionally, description fields in the Saleor API have changed type from String to JSONString in the following objects:

  • Category
  • Collection
  • Product
  • Translation for objects listed above

Pages changed content field type in the same way.

Product and Variant Images

Saleor 3.0 extends the possibilities for presenting your products to customers. Now, you can use photos and videos. The old image attribute and the ProductImage objects are left for backward compatibility but marked as deprecated. If you want to leverage all new features, please use ProductMedia.

Read documentation for the ProductMedia.

Removed fields from the Shop object

The Shop.homepageCollection field has been removed. The recommended way of getting a specific collection data in such a situation is to create a new collection and use the collection query with the desired slug, for example:

query FeaturedProducts {
collection(slug: "featured", channel: "default-channel") {
products(first: 10) {
edges {
node {
name
}
}
}
}
}

Shop.navigation has been dropped in favor of querying the desired menu by a slug:

query MainMenu {
menu(slug: "main-menu", channel: "default-channel") {
name
items {
name
}
}
}

Shop.geolocalization has been removed.

Error handling

The new version unifies error handling across the API. All mutation responses have an errors field. It contains detailed information about the issue(s). For example:

mutation {
checkoutCreate(input: { lines: [] }) {
errors {
field
message
code
}
}
}

Server response:

{
"data": {
"checkoutCreate": {
"errors": [
{
"field": "channel",
"message": "You need to provide channel slug.",
"code": "MISSING_CHANNEL_SLUG"
}
]
}
}
}

Error codes can be used for identifying the issue and displaying custom message for the customers.

Product filters

The API for searching and filtering products has been changed.

Read the documentation for product filters and sorting.

Attributes

Attribute:

  • Attribute.values dropped in favor of paginated list called choices. AttributeValue type:
  • Attribute.type: AttributeValueType dropped. Use the inputType field to determine the type of attribute's value.

AttributeValueInput:

  • value: String changed to values with type [String!]

Invoices

  • The invoiceSendEmail mutation is renamed to invoiceSendNotification.

Permissions

  • MANAGE_SERVICE_ACCOUNTS was removed. Use MANAGE_APPS for managing external apps.
  • MANAGE_PRODUCT_TYPES_AND_ATTRIBUTES was added. Staff users managing the accounts may need to add this permission.
  • MANAGE_PAGE_TYPES_AND_ATTRIBUTES was added. Staff users managing pages may need to add this permission.

Apps

Service Accounts have been renamed to Apps.

Authorization keys

The following mutations were dropped:

  • authorizationKeyAdd
  • authorizationKeyDelete

If you want to create access tokens, you can do that by creating an App.

Webhooks

Webhook payloads have changed. You can reference examples at our documentation.

The following events have been added:

  • DRAFT_CREATED_FROM_REPLACE
  • ADDED_PRODUCTS
  • REMOVED_PRODUCTS
  • ORDER_REPLACEMENT_CREATED
  • ORDER_DISCOUNT_ADDED
  • ORDER_DISCOUNT_AUTOMATICALLY_UPDATED
  • ORDER_DISCOUNT_UPDATED
  • ORDER_DISCOUNT_DELETED
  • ORDER_LINE_DISCOUNT_UPDATED
  • ORDER_LINE_DISCOUNT_REMOVED
  • ORDER_LINE_PRODUCT_DELETED
  • ORDER_LINE_VARIANT_DELETED
  • CONFIRMED
  • FULFILLMENT_REFUNDED
  • FULFILLMENT_RETURNED
  • FULFILLMENT_REPLACED

Removed:

  • DRAFT_ADDED_PRODUCTS in favor of ADDED_PRODUCTS
  • DRAFT_REMOVED_PRODUCTS in favor of REMOVED_PRODUCTS

The full list of available events can be found here.

Metadata

The privateMeta and meta fields have been renamed to privateMetadata and metadata.

JWT

The signature of JWT tokens has been replaced from HS256 to RS256. This change will require providing an RSA private key for the production environments.