Upgrading From 3.20 To 3.21
To follow the zero-downtime strategy when upgrading to 3.21, It is recommended to first migrate to latest 3.20.X and turn on the Celery worker to process all data migrations asynchronously. Otherwise, you will need to downtime your solution to ensure correct data migration.
Authentication required for changing Order and OrderLine metadata​
The updateMetadata mutation for Order and OrderLine now requires the MANAGE_ORDERS permission.
Once an order is created, customers cannot edit its metadata. However, merchants and apps with the necessary permissions can modify this data.
Fetching metadata remains unchanged.
Merging metadata in transactionUpdate mutation​
The transactionUpdate mutation now merges the provided metadata and private metadata with existing values, instead of overwriting them. To delete a specific metadata entry, use the deleteMetadata mutation. For private metadata, use the deletePrivateMetadata mutation.
Deprecated manager.perform_mutation method​
Note: This change only affects open-source Saleor users with custom plugins overriding the perform_mutation plugin method.
As part of gradual plugin deprecation, Saleor 3.20 deprecates the perform_mutation plugin hook. This method allowed to customize the mutation execution flow and call arbitrary logic during mutation execution. From now on, we recommend building such customizations via apps by reacting to webhooks triggered by mutations. The perform_mutation plugin method will be removed in Saleor 3.21.
Deprecated WebhookPlugin and webhook-related plugin hooks​
Note: This change only affects open-source Saleor users with custom plugins that override webhook-related plugin hooks (see the list below).
The WebhookPlugin is deprecated in Saleor 3.20 and will be removed in Saleor 3.21, as all webhook-related functionality will be moved from plugin to core modules. Rationale behind this change is that webhooks are essential part of Saleor and should be available out of the box, without the need for additional plugins. As a result, multiple plugin manager hooks will be deprecated, as they are only used by the WebhookPlugin.
If you have custom plugins that override any of the following plugin hooks, you should migrate your custom logic to Saleor App that listens to webhooks.
The list of deprecated plugin hooks is as follows:
account_change_email_requestedaccount_confirmation_requestedaccount_confirmedaccount_delete_requestedaccount_deletedaccount_email_changedaccount_set_password_requestedaddress_createdaddress_deletedaddress_updatedapp_deletedapp_installedapp_status_changedapp_updatedattribute_createdattribute_deletedattribute_updatedattribute_value_createdattribute_value_deletedattribute_value_updatedcategory_createdcategory_deletedcategory_updatedchannel_createdchannel_deletedchannel_metadata_updatedchannel_status_changedchannel_updatedcheckout_createdcheckout_fully_paidcheckout_metadata_updatedcheckout_updatedcollection_createdcollection_deletedcollection_metadata_updatedcollection_updatedcustomer_createdcustomer_deletedcustomer_metadata_updatedcustomer_updateddraft_order_createddraft_order_deleteddraft_order_updatedevent_delivery_retryfulfillment_approvedfulfillment_canceledfulfillment_createdfulfillment_metadata_updatedget_shipping_methods_for_checkoutget_taxes_for_checkoutget_taxes_for_ordergift_card_createdgift_card_deletedgift_card_export_completedgift_card_metadata_updatedgift_card_status_changedgift_card_updatedinvoice_deleteinvoice_sentlist_stored_payment_methodsmenu_createdmenu_deletedmenu_item_createdmenu_item_deletedmenu_item_updatedmenu_updatedorder_bulk_createdorder_cancelledorder_createdorder_expiredorder_fulfilledorder_fully_paidorder_fully_refundedorder_metadata_updatedorder_paidorder_refundedorder_updatedpage_createdpage_deletedpage_type_createdpage_type_deletedpage_type_updatedpage_updatedpayment_gateway_initialize_sessionpayment_gateway_initialize_tokenizationpayment_method_initialize_tokenizationpayment_method_process_tokenizationpermission_group_createdpermission_group_deletedpermission_group_updatedproduct_createdproduct_deletedproduct_export_completedproduct_media_createdproduct_media_deletedproduct_media_updatedproduct_metadata_updatedproduct_updatedproduct_variant_back_in_stockproduct_variant_createdproduct_variant_deletedproduct_variant_metadata_updatedproduct_variant_out_of_stockproduct_variant_stock_updatedproduct_variant_updatedpromotion_createdpromotion_deletedpromotion_endedpromotion_rule_createdpromotion_rule_deletedpromotion_rule_updatedpromotion_startedpromotion_updatedsale_createdsale_deletedsale_updatedshipping_price_createdshipping_price_deletedshipping_price_updatedshipping_zone_createdshipping_zone_deletedshipping_zone_metadata_updatedshipping_zone_updatedshop_metadata_updatedstaff_createdstaff_deletedstaff_set_password_requestedstaff_updatedstored_payment_method_request_deletethumbnail_createdtransaction_cancelation_requestedtransaction_charge_requestedtransaction_initialize_sessiontransaction_item_metadata_updatedtransaction_process_sessiontransaction_refund_requestedvoucher_code_export_completedvoucher_codes_createdvoucher_codes_deletedvoucher_createdvoucher_deletedvoucher_metadata_updatedvoucher_updatedwarehouse_createdwarehouse_deletedwarehouse_metadata_updatedwarehouse_updated
checkout.shippingMethods and checkout.availableShippingMethods do not return external shipping methods if their currency differs from the checkout's currency​
If an app subscribed to SHIPPING_LIST_METHODS_FOR_CHECKOUT returns an external shipping method with a currency different from the checkout's currency, Saleor will filter out that shipping method. As a result, external shipping methods with a different currency than the checkout's currency will not be returned via the API (in the checkout.shippingMethods and checkout.availableShippingMethods fields).
Any potential currency validation for external shipping methods on the frontend / app side is no longer necessary.
Blocked external calls for checkout and order bulk queries​
To enhance performance and efficiency, bulk queries that fetch multiple checkout or order objects will no longer trigger external calls to third-party services. The following synchronous webhooks will be affected:
CHECKOUT_CALCULATE_TAXESwebhooksORDER_CALCULATE_TAXESwebhooksSHIPPING_LIST_METHODS_FOR_CHECKOUTwebhooksCHECKOUT_FILTER_SHIPPING_METHODSwebhooksORDER_FILTER_SHIPPING_METHODSwebhooks
External calls from the AvataxPlugin will also be skipped.
Instead of recalculating taxes externally, the system will return pre-stored prices from the database. Additionally, only built-in shipping methods will be returned. The CHECKOUT_FILTER_SHIPPING_METHODS and ORDER_FILTER_SHIPPING_METHODS webhooks will not be triggered, and all built-in shipping methods will be listed as available.
Any external shipping methods assigned to the checkout will still be visible through denormalized data stored in the database.
Affected queries​
The following queries will not trigger external calls:
checkouts(...)me.checkouts(...)checkoutLines(...)orders(...)me.orders(...)draftOrders(...)
Example of impacted queries​
{
checkouts(first: 10) {
edges {
node {
id
deliveryMethod {
... on ShippingMethod {
id
name
}
}
shippingMethods {
id
name
}
totalPrice {
gross {
amount
}
}
}
}
}
}
{
orders(first: 100) {
edges {
node {
deliveryMethod {
... on ShippingMethod {
id
name
}
}
shippingMethods {
id
name
}
total {
gross {
amount
}
}
}
}
}
}
The checkout and order queries will still work as before. If tax information is outdated, external calls will be made to recalculate taxes. External shipping methods and filters will be fetched if necessary.
checkout.privateMetadata no longer stores external-shipping-method-id​
The external-shipping-method-id is no longer stored within checkout.privateMetadata. To retrieve this ID, use the checkout.deliveryMethod field instead.
checkoutDeliveryMethodUpdate and checkoutShippingMethodUpdate mutations do not trigger CHECKOUT_UPDATED webhook or tax invalidation when adding the same method already assigned​
Previously, the checkoutDeliveryMethodUpdate and checkoutShippingMethodUpdate mutations would trigger the CHECKOUT_UPDATED webhook and invalidate taxes regardless of whether the same delivery method was already assigned to the checkout.
Starting from version 3.21, if the same method that is already assigned to the checkout is provided, the CHECKOUT_UPDATED webhook will not be triggered, and taxes will not be invalidated.
From Saleor's perspective, nothing has changed, as the checkout remains in the same state as it was before the mutation was called.
Introduced price freeze period for editable orders​
In previous versions, all editable orders (those with DRAFT and UNCONFIRMED statuses) refreshed their base prices
by fetching them from the current product catalog during each recalculation.
Additionally, all discounts were applied based on the latest reward values.
To ensure price consistency over time, regardless of updates to the product catalog, Saleor has introduced a price freeze period.
During this period, order lines use denormalized base prices instead of retrieving them from the catalog.
More details can be found here
- Draft orders: the base prices are frozen for 24 hours by default. This duration can be modified using the
Channel.draftOrderLinePriceFreezePeriodsetting. - Unconfirmed orders: the base prices remain frozen indefinitely, and this setting is not configurable.
- Other orders: remain unchanged and cannot be recalculated.