Saleor 3.22.0 — Release Notes & Engineering Impact

> [!NOTE] > Pages have been renamed to Models in Saleor Dashboard (Model Types for Page Types). The API currently still uses the Page and PageType names for backward compatibility. ## Highlights ### 🎯 Advanced Data Modeling Saleor 3.22 introduces new features to make our modeling system even more powerful. **New `SINGLE_REFERENCE` attribute type**: Create one-to-one relationships between data entities. Unlike `REFERENCE` which allows multiple references, `SINGLE_REFERENCE` enforces a single relationship - useful for primary categories, featured products, or hierarchical structures. **Powerful attribute-based filtering**: Models (Pages in API) support filtering by any attribute type - numeric values, booleans, dates, and references. Find models that reference specific products, variants, categories, or collections using flexible matching strategies (`containsAll` or `containsAny`). > [!NOTE] > Please note that new filtering in models is not yet available in Saleor Dashboard. It will be added in one of the next patch releases. **Reference type restrictions**: Control which objects can be selected in reference attributes by specifying allowed product types or model types. This prevents invalid references and provides precise control over data relationships. **Categories and collections as references**: `AttributeEntityType` enum now includes `CATEGORY` and `COLLECTION`, enabling reference attributes that point to these entities. **Filtering by product’s attribute value:** Products can now be filtered based on`REFERENCE` and `SINGLE_REFERENCE` attribute’s referenced object: ID, slug, SKUs. **Optional attribute slugs**: When filtering products or variants by reference attributes, you no longer need to specify which attribute contains the reference - simplifying queries significantly. ### 🔍 Enhanced Filtering The new `where` and `search` system replaces the old `filter` argument (which was marked as deprecated), bringing more powerful querying capabilities: **Orders & Draft orders**: Filter by voucher codes, invoice existence / creation date, fulfillment status, payment method details, total amounts, product types, billing/shipping addresses, and more. The full-text search ranks results by relevance across order numbers, customer information, addresses, products, and events (details about ranking system are in the full release notes). Orders can now also be sorted by status. > [!NOTE] > Please note new filter features for draft orders are not yet available in Saleor Dashboard. They will be released in next patch releases. Orders filtering is already available. **Customers**: Filter by email, name, active status, address details, phone numbers, and order count. Search across all customer and address book data. > [!NOTE] > Please note that new filter features for customers are not yet available in Saleor Dashboard. They will be released in next patch releases. </aside> **Models (**previously Pages)**:** Migrated existing filters to, added support to filter by attributes (described above). **Products:** Filtering by category now also includes subcategories, other changes are described in previous section. ### 💳 Structured Payment Method Details Payment apps can now store structured payment information directly on transactions: - **Card payments**: Store card’s brand, first/last 4 digits, expiration date - **Other payment methods**: Store payment method name This standardization makes payment data type-safe, searchable, and consistent across all payment apps. Details can be provided via transaction mutations or webhooks. The `Money` type also gains `fractionalAmount` and `fractionDigits` fields for better payment provider integration, and helps avoid floating point operation errors. > [!WARNING] > Transactions created before 3.22 will not have these new details. Support for payment details for newly created transactions depends on app’s support. > [!WARNING] > Previously some apps (e.g. Adyen App) stored payment method information in `TransactionItem` metadata. We recommend to migrate existing integrations to use the new `PaymentMethodDetails` object. We plan to phase out usage of `metadata` in apps to store this informations in the future. ### 🎨 Expanded App Extensions Apps can now extend more areas of Dashboard: - **NEW_TAB target**: Open extensions in new browser tabs - **WIDGET target**: Embed iframe widgets directly in Dashboard pages - **Additional mounting points** across categories, collections, gift cards, draft orders, discounts, vouchers, models, and more ### 💰 Refund Reasons Configuration Configure required refund reasons using Models to standardize and track why refunds are issued. Create a Model Type for refund reasons, add specific reasons as models, and require staff users to select a reason when processing refunds. Custom refund messages are still available along with configured refund reason. ### ✅ JSON Schemas Our sync webhooks are now using JSON Schema for validation which is available in `saleor/json_schemas.py`. This improves type safety when building apps that integrate with Saleor using sync webhooks. --- ## Breaking Changes - The following changes were implemented to orders with a zero total amount: - No manual charge (`Transaction` or `Payment`) object will be created. - The `OrderEvents.ORDER_MARKED_AS_PAID` event will no longer be emitted. - Logic associated with `WebhookEventAsyncType.CHECKOUT_FULLY_PAID` event will no longer be triggered when creating a transaction event from webhook response for checkouts with having total gross being 0. At the point of creating the transaction event checkout is already considered fully paid. - Creating a Payment (old API) for a Checkout object with an existing Transaction (new API) is no longer permitted as it leads to inconsistent behavior. - Webhooks are no longer triggered for deactivated Apps.