Adrian Pilarczyk

Saleor 3.10 & 3.11: webhook testing, external references and new filtering API preview

This article highlights the most significant changes from releases 3.10 and 3.11 of Saleor. They include updates to product management, a preview of the new filtering API, as well as some productivity boosts in clever implementations of the GraphiQL Playground.

See the following changelogs for a complete list of changes in each release:

Now, let's go through their highlights.


Saleor 3.10

Filtering and sorting category products

We start with a special treat from our community. Specifically, the GitHub users: @yemeksepeti-cihankarluk and @ogunheper.

Thanks to their work, we can now filter and sort the category products similarly to collection products.

Let’s put this to use. Imagine you want to fetch all of a category’s published products. With the new filtering mechanism, the query would look like this:

{
category(id: "Q2F0ZWdvcnk6MjU=") {
products(filter: {isPublished: true}, channel: "default-channel", first: 10) {
edges {
node {
id
}
}
}
}
}

External references

external_reference is a new field that allows for identifying an object based on its id from an external system. This may come in handy when integrating Saleor with other services.

Let’s say we want to implement a two-way integration between Saleor and a CMS. Whenever a product is created in Saleor, we want to create a corresponding product in the CMS. Once a product is created in the CMS, it is assigned an id. We can take that id and update the Saleor product’s external_reference with it.

From now on, whenever we want to update a Saleor product from the CMS, we can use the external_reference field:

mutation {
productUpdate(externalReference: "CMS_ID", input: { name: "New name" }) {
errors {
field
message
}
}
}

external_reference will be applied to the following models:

  • Orders
  • Products
  • Product Variants
  • Attributes
  • Attribute Values
  • Warehouses
  • Customers

Saleor 3.11

Preview of the new filtering API

The new filtering API revolves around the where keyword. It allows constructing and combining complex logical expressions using the AND, OR, and NOT operators. This way, the user gets complete control over the conditions the data needs to meet to be returned from the query.

We’ve added the where API to the first query: the attributes query. Here is how fetching attributes that name is Author or slug is tom or james, looks like with the new API:

{
attributes(
where: {NOT: {AND: [{name: {eq: "Author"}}, {slug: {oneOf: ["tom", "james"]}}]}}
) {
edges {
node {
id
}
}
}
}

These changes are part of a bigger filter overhaul. We described it in detail in the “Filters improvement” RFC.

Bulk mutation for updating product variants

We’ve introduced a new mutation for updating multiple product variants simultaneously - productVariantBulkUpdate.

Mutation example:

mutation ProductVariantBulkUpdate(
$variants: [ProductVariantBulkUpdateInput!]!,
$productId: ID!,
$errorPolicy: ErrorPolicyEnum
) {
productVariantBulkUpdate(
variants: $variants, product: $productId, errorPolicy: $errorPolicy
) {
results {
errors {
field
message
code
warehouses
channels
}
productVariant{
id
name
sku
stocks {
warehouse {
slug
}
quantity
}
channelListings {
channel {
slug
}
price {
currency
amount
}
costPrice {
currency
amount
}
preorderThreshold {
quantity
}
}
}
count
}
}

Example ProductVariantBulkUpdateInput data:

[
{
"id": "ASD1=",
"name": "NewName",
"channelListings": [
{
"price": 50.00,
"channelId": "CHN1=,
}
],
"stocks": [
{"quantity": 10, "warehouse": "WRH1="},
{"quantity": 50, "warehouse": "WRH2="},
],
},
{
"id": "ASD2=",
"channelListings": [
{
"price": 50.00,
"channelId": "CHN1=",
},
{
"price": 120.00,
"channelId": "CHN2=",
}
],
},
]

We also updated the productVariantBulkCreate mutation with a new error policies feature and field results that should be used to fetch data. The old field product_variants will be deprecated in the future.

type ProductVariantBulkResult {
productVariant: ProductVariant
errors: [ProductVariantBulkError!]!
}

Error policies for bulk mutations are introduced as a preview feature. Now users can decide how it should behave by passing the errorPolicy argument to bulk mutation when an error occurs. As the default error policy, we use REJECT_EVERYTHING. To check available error policies, look at ErrorPolicyEnum :

enum ErrorPolicyEnum {
# Save what is possible within a single row. If there are errors in an input data row, try to save it partially and skip the invalid part.
IGNORE_FAILED
# Reject rows with errors.
REJECT_FAILED_ROWS
# Reject all rows if there is at least one error in any of them
REJECT_EVERYTHING
}

productVariantBulkCreate, productVariantBulkDelete, and productVariantBulkUpdate complete the list of basic bulk operations for product variants.

Waiting for anticipated bulk product operations? Make sure to tune in to the next release articles 👀.

Subscription webhooks dry run mode

The 3.11 version also brings a new section in the Dashboard’s Webhook view: the dry run playground. It allows you to execute a test run of a selected webhook.

drygif blog.gif

To try out a webhook dry run, you need:

  • subscription payload
  • object target

You can define the payload for your webhook subscription on the left side of the GraphiQL playground. Don’t worry about pointing to the right webhook event: it gets inferred from the webhook declaration.

Then, initiate the dry run by clicking the ▶️ button. It will open a modal where you select a targeted payload object:

On the left side of the modal, select an object type related to the webhook’s event. In the video above, we defined a subscription on the ProductUpdated event, so that will be a product.

On the right side, choose an item that represents that object. The item will be returned in the defined subscription payload. In the video example, we use the “Apple Juice” product.

After the dry run has been successfully executed, you can confirm the delivery of your subscription on a real sample.

Open a product or order in the GraphiQL Playground

Dashboard views link products or orders to the GraphiQL Playground. It can have a variety of different use cases: from exploration to debugging.

You can find the feature in both the product’s and the order’s detail view under the “gear” icon:

graphiql redirect gif.gif


In this blog post, we highlighted some of the key changes and improvements in Saleor 3.10 and 3.11. Follow our Twitter and sign up for our newsletter to stay up to date with the latest info about Saleor!

By accepting our usage of third-party software such as Google Tag Manager, you help us to deliver a better website experience to all our users. To see our full privacy policy, click here (links to Privacy Policy).