nevaberry Saleor Knowledge Patch
Load this skill when designing, upgrading, or debugging Saleor GraphQL clients, storefronts, apps, Dashboard extensions, payment integrations, or deployments. Use the index to open the reference file for the area being changed, then apply the quick-reference rules below before relying on older contracts.
[!CAUTION] Guidance marked
upcoming-3.24is prerelease guidance and may change before stable release.
Reference index
| Reference | Topics |
|---|---|
| api-auth-and-search.md | GraphQL input and nullability changes, authentication, accounts, permissions, filters, and search |
| checkout-orders-and-delivery.md | Checkout and order mutations, delivery calculation, address persistence, events, metadata, and base prices |
| payments-transactions-and-discounts.md | Transaction and payment contracts, refunds, invoices, discounts, money, gift cards, and exports |
| apps-webhooks-and-extensions.md | Synchronous and asynchronous webhooks, circuit breaking, app lifecycle, extensions, and subscriptions |
| catalog-attributes-and-content.md | Products, variants, attributes, models, translations, stock, media, and digital content |
| operations-and-observability.md | Deployment configuration, telemetry, JWKS, rich text, staff deletion, and bulk limits |
Breaking changes and removals
Move checkout delivery clients to the explicit delivery contract
Call deliveryOptionsCalculate when shipping integrations must run. Consume
Checkout.delivery instead of deprecated shippingMethod and
deliveryMethod, and pass a CheckoutDelivery ID to
checkoutDeliveryMethodUpdate.deliveryMethodId. Treat a stale delivery problem
as non-blocking and revalidatable, but require a valid delivery before
completion when the problem is invalid.
Update app-extension field names
Use settings, mountName, and targetName on AppExtension and
AppManifestExtension; options, mount, and target were removed. A
manifest may still provide string mount/target and JSON options, whose
contract is validated by Dashboard rather than Saleor.
Remove remaining built-in payment-plugin dependencies
Adyen and NP Atobarai gateway plugins have been removed in favor of their apps,
and Payment.partial is gone. The old invoicing plugin and deprecated
mirumee.payments.stripe plugin are also gone; use an invoice app and
saleor.payments.stripe references.
Prerelease gateway removals
Prerelease (
upcoming-3.24): This guidance may change before stable release.
Authorize.Net, Razorpay, Braintree, Dummy, and Dummy Credit Card built-in plugins are removed. Migrate deployments that still use them before upgrading.
Rewrite prerelease checkout mutation calls
Prerelease (
upcoming-3.24): This guidance may change before stable release.
Use id instead of checkoutId in checkout address updates. Replace
checkoutLineDelete with checkoutLinesDelete, passing linesIds and only the
checkout id. checkoutCreate.lines is optional and may be omitted to create
an empty checkout.
Move prerelease shop and order settings
Prerelease (
upcoming-3.24): This guidance may change before stable release.
Replace shopDomainUpdate with PUBLIC_URL. Replace orderSettingsUpdate and
the orderSettings query with channelUpdate(orderSettings: ...) and
channel.orderSettings. Remove use of shopFetchTaxRates and
ShopFetchTaxRates; use a tax configuration mutation such as
taxConfigurationUpdate.
Replace removed and deprecated order, product, and checkout fields
Prerelease (
upcoming-3.24): This guidance may change before stable release.
Replace orderAddNote with orderNoteAdd, Order.availableShippingMethods
with shippingMethods, Product.variant with the top-level variant query,
and Checkout.note with customerNote.
Move attribute presentation policy out of removed flags
Prerelease (
upcoming-3.24): This guidance may change before stable release.
Do not use filterableInStorefront, filterableInDashboard,
availableInGrid, or storefrontSearchPosition in attribute fields, inputs,
filters, or related sort enums. Put presentation logic in the client or in
attribute metadata; the unused database columns remain temporarily.
Webhook and app behavior
Validate synchronous responses before returning them
Saleor strongly validates types, string lengths, and numeric ranges in shipping,
tax, and payment/transaction synchronous-webhook responses. Invalid shipping
responses are logged and ignored. Invalid tax or payment responses are recorded
on the checkout, order, or transaction event and stop checkout or order
processing. Apps can import the same JSON Schemas from
saleor/json_schemas.py.
Do not depend on read or async-event side effects
Checkout and order read queries do not invoke tax or shipping integrations. Preparing async order, draft-order, or fulfillment events also does not pre-fire their synchronous hooks. Run integrations through the paths that actually request their data.
Account for no-op and deactivated delivery suppression
No-op draft-order and order updates suppress update webhooks, and unchanged shipping-method availability suppresses filter webhooks. Deactivated apps receive neither asynchronous nor synchronous webhooks.
Roll out the circuit breaker deliberately
The synchronous-webhook circuit breaker is disabled by default. It can first monitor errors in dry-run mode, then selectively block an app after its error threshold is crossed.
Checkout, order, and stock behavior
Choose address persistence explicitly
Checkout and checkout-address mutations, plus draft-order create/update, accept
saveBillingAddress and saveShippingAddress. Supply a valid address input.
Without an override, checkouts save addresses and draft orders do not; Click &
Collect never saves a shipping address.
Choose the stock-availability model
Shop.useLegacyShippingZoneStockAvailability selects legacy address and
shipping-zone filtering or direct warehouse-channel availability. Existing
installations default to legacy behavior. Setting it to false changes stock
validation, reservation, allocation, fulfillment, availability, and relevant
webhook warehouse selection; address arguments are deprecated and ignored in
direct-link mode.
Preserve explicit mutation semantics
transactionUpdate merges metadata maps rather than replacing them. Updating
Order or OrderLine metadata requires MANAGE_ORDERS. UNCONFIRMED orders
never refresh denormalized base prices, while DRAFT orders refresh them after
a default of 24 hours.
Payment and transaction behavior
Use transaction action amounts as the fallback
Refund, charge, and cancelation request subscription actions expose a non-null
amount. When an app omits amount from the listed charge, refund, cancelation,
initialize, or process response, Saleor uses the payload's action.amount.
Store payment-method details structurally
Payment apps may provide PaymentMethodDetails, including supported card
details or a non-card method name, through transaction mutations or webhooks.
Older transactions are not backfilled and apps must explicitly support the
fields. Move these values out of TransactionItem metadata.
Keep legacy payments separate from transactions
Do not create a legacy Payment for a checkout that already has a
Transaction. A manual charge on a zero-total order creates neither object nor
an ORDER_MARKED_AS_PAID event.
Avoid floating-point money calculations
Use Money.fractionalAmount with Money.fractionDigits when an integration
needs an integer amount and currency precision.
Search, accounts, and permissions
Migrate filters to where and search
Orders, draft orders, customers, and Pages use the newer filter/search system;
the older filter arguments are deprecated. Search supports prefix matching,
Boolean operators, quoted phrases, accent-insensitive matching, and relevance
ordering, including explicit RANK sorting.
Treat registration state as concealed
Account registration and recovery mutations do not reveal whether an email is
registered, and accountRegister no longer returns a user ID. Non-staff
password-reset requests no longer fail solely because channel is omitted.
Enforce prerelease permission distinctions
Prerelease (
upcoming-3.24): This guidance may change before stable release.
Reject MANAGE_APPS in app installation requests. For attribute mutations,
require the permission matching the attribute type; a bulk request spanning
types requires all matching permissions, and MANAGE_PRODUCTS no longer
authorizes attributeValueCreate.
Distinguish omitted, null, and empty app permissions
Prerelease (
upcoming-3.24): This guidance may change before stable release.
On appCreate, omitted or null permissions creates an app without
permissions. On appUpdate, omitted or null preserves permissions, while an
empty list clears them.