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.
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.
DraftOrderUpdate mutation no longer calls DRAFT_ORDER_UPDATED webhook if nothing has changed
The DraftOrderUpdate mutation no longer triggers the DRAFT_ORDER_UPDATED webhook event if there are no changes to the draft order.
This adjustment ensures that the event is only fired when there are actual updates to the draft order, reducing unnecessary event emissions.
OrderUpdate mutation no longer calls ORDER_UPDATED webhook if nothing has changed
The OrderUpdate mutation no longer triggers the ORDER_UPDATED webhook event if there are no changes to the draft order.
This adjustment ensures that the event is only fired when there are actual updates to the order, reducing unnecessary event emissions.
Required transactionId field in OrderGrantRefundCreateInput
The OrderGrantRefundCreateInput now requires a transactionId field.
This change affects the OrderGrantRefundCreate mutation.
The transactionId must be provided as part of the input; otherwise, the mutation will return an error.
Plugin changes
Removed plugins
The invoicing plugin was removed. There is no direct replacement available. See https://github.com/saleor/example-app-invoices for an example of a replacement app.
The "Stripe (Deprecated)" (mirumee.payments.stripe) plugin was removed. Use the "Stripe" (saleor.payments.stripe) plugin instead or see https://github.com/saleor/saleor-app-payment-stripe for an example of a replacement app.
Deprecated manager.perform_mutation method
Note: 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: Affects open-source Saleor users with custom plugins that override webhook-related plugin hooks (see the list below).
The WebhookPlugin is deprecated and will be removed in a future release, 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
change_user_address method removed from Plugin Manager
Note: Affects open-source Saleor users with custom plugins overriding the change_user_address plugin method.
The change_user_address method has been removed from the Plugin Manager and is no longer available.
Changed order status behavior for WAITING_FOR_APPROVAL fulfillments
In previous versions, orders that had any unapproved fulfillments and no returns, were given status PARTIALLY_FULFILLED. This happened even when no items were actually fulfilled.
Currently, fulfillments with WAITING_FOR_APPROVAL status are excluded from determination of order status. Adding unapproved fulfillment to order will no longer result in a status change.
Order can only receive PARTIALLY_FULFILLED status if there exists FULFILLED fulfillment and there are some items that are either unfulfilled or awaiting approval.
Changes to discount propagation in orders created from checkout
In Saleor 3.21, discount propagation for orders created from checkout has been standardized to match the behavior of draft orders, ensuring consistent handling of vouchers and promotions across all order types. Below, you’ll find details on how discount propagation now behaves for different types of discounts.
Voucher handling before version 3.21
In versions prior to 3.21, how vouchers were applied and represented depended on how the order was created:
| Order source | SPECIFIC_PRODUCT voucher | ENTIRE_ORDER with apply-once-per-order voucher |
|---|---|---|
| Checkout | Represented as OrderDiscount in order.discounts | Represented as OrderDiscount in order.discounts |
| Draft order | Not included in order.discounts | Not included in order.discounts |
Additionally, percentage-based vouchers applied during checkout were automatically converted to fixed-value discounts, while draft orders retained the original percentage type:
| Order source | SPECIFIC_PRODUCT (percentage) | ENTIRE_ORDER with apply-once-per-order (percentage) |
|---|---|---|
| Checkout | Converted to FIXED | Converted to FIXED |
| Draft order | Retained as PERCENTAGE | Retained as PERCENTAGE |
Changes introduced in version 3.21
Starting in version 3.21, voucher propagation is consistent across all order types:
- All orders created via checkout now use
OrderLineDiscountobjects for bothSPECIFIC_PRODUCTandENTIRE_ORDER(withapply-once-per-order) vouchers — same as draft orders. - Percentage-based vouchers are no longer converted to fixed-value discounts. The original
PERCENTAGEtype is preserved and correctly represented in the API.
Changes to unitDiscountReason and unitDiscount.amount for orders created from checkout
Previously, for orders created via checkout using a Voucher:ENTIRE_ORDER, the discount was represented in two ways:
- As an
OrderDiscountobject inorder.discounts - As a proportional amount in each line’s
unitDiscount.amount, along with a correspondingunitDiscountReason
Before version 3.21
| Order source | unitDiscountReason | unitDiscount.amount |
|---|---|---|
| Checkout | Included reason for ENTIRE_ORDER discount | Included line-level portion of the ENTIRE_ORDER discount |
| Draft order | Reason for ENTIRE_ORDER discount not included | Line-level portion of the ENTIRE_ORDER discount not included |
This also applied to discounts from active OrderPromotions:
| Order source | unitDiscountReason | unitDiscount.amount |
|---|---|---|
| Checkout | Included reason for promotion discount | Included line-level portion of promotion discount |
| Draft order | Reason for promotion discount not included | Line-level portion of promotion discount not included |
After version 3.21
As of version 3.21, unitDiscountReason and unitDiscount.amount no longer include information related to:
Voucher:ENTIRE_ORDERdiscountsOrderPromotiondiscounts
This behavior is now consistent with how draft orders work.
Backward compatibility: useLegacyLineDiscountPropagation feature flag
To maintain compatibility with existing integrations, version 3.21 introduces a feature flag: useLegacyLineDiscountPropagation, which allows you to configure the discount propagation behavior per channel.
This flag controls how voucher and promotion discounts appear in the API for orders created via checkout.
How discounts are represented based on the flag
| Checkout order + voucher | 3.20 | 3.21 + Legacy propagation enabled | 3.21 + Legacy propagation disabled |
|---|---|---|---|
SPECIFIC_PRODUCT | OrderDiscount (in order.discounts) | OrderDiscount (in order.discounts) | OrderLineDiscount (in OrderLine.discounts) only |
ENTIRE_ORDER + apply-once-per-order | OrderDiscount (in order.discounts) | OrderDiscount (in order.discounts) | OrderLineDiscount (in OrderLine.discounts) only |
Discount type (FIXED vs PERCENTAGE) based on the flag
| Checkout order + percentage voucher | 3.20 | 3.21 + Legacy propagation enabled | 3.21 + Legacy propagation disabled |
|---|---|---|---|
SPECIFIC_PRODUCT (percentage) | Converted to FIXED | Converted to FIXED | Retained as PERCENTAGE |
ENTIRE_ORDER (percentage) | Converted to FIXED | Converted to FIXED | Retained as PERCENTAGE |
unitDiscountReason and unitDiscount.amount based on the flag
| Checkout order + voucher type | 3.20 | 3.21 + Legacy propagation enabled | 3.21 + Legacy propagation disabled |
|---|---|---|---|
Voucher:ENTIRE_ORDER | Included in unitDiscountReason & unitDiscount.amount | Included in unitDiscountReason & unitDiscount.amount | Not included in unitDiscountReason & unitDiscount.amount |
OrderPromotion | Included in unitDiscountReason & unitDiscount.amount | Included in unitDiscountReason & unitDiscount.amount | Not included in unitDiscountReason & unitDiscount.amount |
Default behavior
- Existing channels:
useLegacyLineDiscountPropagationis enabled by default - New channels: the flag is disabled by default, unless explicitly set otherwise
Changing the useLegacyLineDiscountPropagation flag only affects orders created after upgrading to version 3.21.
It does not retroactively change:
- Discount types for vouchers already converted from
PERCENTAGEtoFIXED unitDiscountReasonandunitDiscount.amountfields on existing orders
Creating new channel with legacy flow enabled
If you need to create a new channel with the legacy voucher propagation flow active, you must explicitly set useLegacyLineDiscountPropagation in the channelCreate mutation input:
mutation {
channelCreate(
input: {
name: "New channel"
slug: "new-channel"
currencyCode: USD
defaultCountry: PL
orderSettings: {
useLegacyLineDiscountPropagation: true
}
}
) {
channel {
id
}
errors {
field
message
}
}
}
By default, new channels have legacy propagation disabled unless this field is explicitly set to true.
Example
The examples below show how order line discounts are represented in the GraphQL response, depending on the useLegacyLineDiscountPropagation configuration.
With useLegacyLineDiscountPropagation enabled:
{
"data": {
"order": {
"id": "T3JkZXI6NzJiM2NhNjktNzJmYS00ZjQ5LWE3ZGMtOTgxZGI4MDIwNmJj",
"discounts": [
{
"id": "T3JkZXJEaXNjb3VudDo1NjhhMGE5OS1hY2Y1LTQ1NzctYjE2YS0zNjFlMjU3MTAyYmE=",
"name": "My voucher",
"type": "VOUCHER",
"valueType": "FIXED",
"value": 11,
"total": {
"amount": 11,
"currency": "USD"
},
"amount": {
"amount": 11,
"currency": "USD"
}
}
],
"lines": [
{
"unitDiscount": { "amount": 3.67 },
"discounts": []
},
{
"unitDiscount": { "amount": 0 },
"discounts": []
}
]
}
}
}
With useLegacyLineDiscountPropagation disabled:
{
"data": {
"order": {
"id": "T3JkZXI6NzJiM2NhNjktNzJmYS00ZjQ5LWE3ZGMtOTgxZGI4MDIwNmJj",
"discounts": [],
"lines": [
{
"unitDiscount": { "amount": 3.67 },
"discounts": [
{
"name": "My voucher",
"type": "VOUCHER",
"valueType": "FIXED",
"value": 11,
"unit": { "amount": 3.67 },
"total": { "amount": 11 }
}
]
},
{
"unitDiscount": { "amount": 0 },
"discounts": []
}
]
}
}
}
How to migrate to the new flow
To fully support the updated propagation model:
- Extend webhook subscriptions to include:
order.lines[].discounts[] - Update all queries to retrieve
OrderLineDiscountdata fromorder.lines[].discounts[] - Adjust internal logic to rely on line-level discount data
- Disable legacy propagation using the following mutation:
mutation {
channelUpdate(
id: "<channel-id>"
input: { orderSettings: { useLegacyLineDiscountPropagation: false } }
) {
channel {
orderSettings {
useLegacyLineDiscountPropagation
}
}
}
}
Google Cloud Platform (GCP): Configuration Changes
The environment variable GS_MEDIA_BUCKET_NAME no longer applies for files that may contain sensitive information. The following steps should be taken:
- Keep the original configuration for
GS_MEDIA_BUCKET_NAME- it will still be used for public media files, such as product images. - Set a new environment variable
GS_MEDIA_PRIVATE_BUCKET_NAME- it should point to a private bucket that's not exposed to the Internet.
For more information, see Storing Files on Google Cloud Storage (GCS).