VTEX Release Notes

FastStore v4.5.0 expands My Account for B2B Buyer Portal (closed beta) with a quotes list and contract switcher, adds CMS-configurable product recommendations and custom account pages, and improves multi-locale PDP and PLP URL resolution. It also forwards Intelligent Search Pricing Fallback tokens into Checkout and copies self-hosted fonts from public/ during CLI generation. See the sections below for more details.

Follow the instructions in Updating the CLI package version to upgrade to v4.5.0 and keep your store up-to-date with the following improvements.

Features

New RecommendationShelf native component (PRs: #3403 | #3414)

Adds a CMS-configurable RecommendationShelf component that fetches VTEX personalization recommendations for a campaign VRN and renders them with the shared core ProductCard. After upgrading to v4.5.0, add the Recommendation Shelf section in the CMS and on the desired page with a valid campaign VRN. For more information on how to use this component, see the Displaying product recommendations with the Recommendation Shelf guide.

Copy fonts and nested assets from public/ folder to build (PR: #3412)

@faststore/cli copyPublicFiles previously dropped nested directories and mismatched extensions, so self-hosted fonts under public/fonts/ never reached the production build. Font formats (.woff, .woff2, .ttf, .otf, .eot) and nested directories are now copied correctly.

Stores that place fonts or nested assets in public/ should upgrade to v4.5.0 and re-run the build.

Forward Pricing Fallback price token to Checkout (PR: #3415)

When Intelligent Search emits a signed price token during a Pricing System incident, FastStore now forwards it through to Checkout so shelf prices can be trusted at add-to-cart. The field is optional: when Search omits it, behavior matches previous releases.

Accounts with the Intelligent Search Pricing Fallback flag enabled after upgrade to v4.5.0 should ensure the store Pricing Fallback flag is on for the account.

Localization feature (closed beta)

Localized product URLs and breadcrumbs on PDP and PLP (PR: #3402)

PDP and PLP slugs, breadcrumbs, and alternate-locale links now resolve correctly for multi-language catalogs.

Retiring pagetype on the collection path in favor of the typed by-linkid cascade changes two observable behaviors. Neither is a schema change (no query breaks), but both are worth calling out for stores that rely on them:

• StoreCollection.type no longer returns Cluster or SubCategory. Clusters and curated collections are both served by collection/by-linkid, so clusters now report as Collection. The category response doesn't expose tree depth beyond root, so third-level categories now report as Category. Both enum values remain declared for backward compatibility.
• Slugs that exhaust the cascade now return 404 instead of falling back to full-text search.

pagetype implicitly promoted unmatched single-segment slugs to a full-text search; the new cascade returns a not-found error when category, brand, and collection resolution all miss.

Stores that branch on collection { type } or rely on the search fallback for unmatched slugs should review those paths after upgrading to v4.5.0.

My Account for B2B Buyer Portal (closed beta)

Quotes list for B2B buyers in My Account B2B Buyer Portal (PR: #3388)

B2B buyers with an organization unit can now open /pvt/account/quotes in My Account to review submitted quotes, with filtering (status and created/expiry date ranges), pagination, status badges, and navigation to order entry.

B2B contract switcher in the account drawer (PR: #3390)

B2B buyers can now view active contracts and switch between them for their Organization Unit directly from the FastStore account drawer. Confirming a switch refreshes the webstore token and reloads the page so commercial context resets. Local development may need authenticator / vtexid rewrites for non-WebOps environments.

Prevent My Account 500s from an empty session profile and missing CMS content (PR: #3417)

My Account routes could previously return error 500 when a representative session had an empty VTEX profile or when a My Account content type had no published CMS content. Both cases are now handled, including a fallback for /pvt/account/404.

CMS-driven custom My Account pages (PR: #3411)

Stores can now declare a My Account route bound to a CMS content type so new account pages are authored in CMS Admin instead of remaining code-only. An optional contentType on each Route in navigation.ts controls the mode: content type alone generates a CMS-only page; content type plus a .tsx page keeps a hybrid of CMS sections and code; omitting contentType preserves legacy code-only routes.

After upgrading to v4.5.0, add contentType on the desired route, sync CMS schemas, publish sections in Admin, and open the route while logged in. Existing routes without contentType are unchanged.

Original source

We've launched a new version of the order listing in the VTEX Admin, now available in open beta. This new experience offers a redesigned interface for viewing and managing orders while keeping the current (legacy) order listing available, so you can switch back to it at any time during the beta.

Why did we make this change?

We've rebuilt the order listing to provide a more modern, consistent experience in the VTEX Admin. This update is available to accounts participating in the open beta for the Orders module.

What needs to be done?

To access this improvement, contact VTEX Support and request activation of this feature for your account.

If you'd like to switch back to the previous version, click the button in Orders, then click Use old experience.

Original source

The Reports endpoints in the VTEX Ads API now enforce a rate limit of 100 requests per minute per account. The limit applies only to API Key-authenticated calls.

What has changed?

• Reports endpoints are limited to 100 requests per minute per account.
• Requests that exceed the limit receive 429 Too Many Requests with the error message Rate limit exceeded for this account.
• Only API Key-authenticated calls to Reports endpoints are affected.

What needs to be done?

If your integration runs large-scale data exports, such as historical loads or full daily syncs, spread requests over time and wait for the next window before retrying after a 429 response.

Contact our support if your integration needs a higher volume.

Learn more

• Exporting ads reports guide.
• VTEX Ads API reference.

Original source

What has changed?

We're launching a new promotion view in the Orders module that shows which promotions were applied to each order item, along with the cart benefits those items triggered. With this update, store operators can view a detailed breakdown of discounts directly on the order details page, without leaving the order details page or checking promotions elsewhere. This feature is available globally in open beta and needs to be enabled upon request.

Previously, the order details page didn't show how promotions were applied to each order item. Now, the Orders module displays promotion details for each order item, allowing you to see exactly which promotions were applied and their impact.

The promotion view is available in different areas of the Orders module:

• Product line items in suggested packages, issued invoices, returned items, and ERP notification packages.
• All items modal, the complete item listing accessed from the order details sidebar.
• Invoice creation flow, where each item displays a breakdown of promotions.

The view supports the following promotion types: Regular, Progressive Discount, Buy Together, More for Less, Buy One Get One, and Campaign Promotion.

You'll see the following elements:

• Promotion badge: A green badge next to the product row indicating that one or more promotions have been applied. When there are multiple promotions, the badge displays the quantity. Gift items (from Buy One Get One promotions) display a Gift badge.
• Promotion popover: Hovering over the badge opens a breakdown with two sections. Each row shows the promotion type, name, and discount amount, plus a Total Discount when multiple promotions are applied. The two sections are as follows:
  • Promotions applied to the item: Discounts at the item level.
  • Promotions applied to the cart: Shipping discounts and other discounts at the cart level.
• Strikethrough price: The original full price appears crossed out next to the effective (discounted) price.

The Orders module in the Admin displays the result of promotions already applied during checkout. It doesn't create or manage promotions. To configure promotions, use the Promotions module.

Why did we make this change?

This update gives you complete visibility into how discounts affect an order, without leaving the order details page. Key benefits include:

• A breakdown of which promotions apply to each item and how much each one discounts.
• A clear view of cart benefits, such as shipping discounts, triggered by order items.
• Faster verification of an order's effective price before issuing invoices or processing returns.

What needs to be done?

This feature is already available in open beta. To test it, open a ticket with VTEX Support requesting access.

Original source

The Checkout API now includes a new Split a cart item endpoint, which splits a single item in a cart into multiple items, distributing its current quantity among them. For example, this allows different shipping or fulfillment rules to be applied to portions of the same SKU.

What changed?

To split a cart item, send a POST request to the Split a cart item endpoint, specifying the cart's orderFormId and the item's uniqueId as the itemUniqueId path parameter. In the request body, provide an array of objects, each with a quantity value. The endpoint will then split the original item into the same number of new items as objects in the array, assigning each new item the specified quantity and a new uniqueId. The total sum of quantity values in the request must exactly match the current quantity of the item being split.

This request fails if the item's noSplitItem field is set to true. To check or change this configuration, use the Handle cart items request.

What needs to be done?

No action is required. This is a new, optional endpoint available for merchants and partners who need to programmatically split cart items.

Original source

The Activity Flow Web Script data-layer plugin now captures add-to-cart events reliably across any storefront and analytics setup. This provides a complete and trustworthy conversion-to-add-to-cart signal across accounts, serving as the north-star metric for measuring search impact directly before checkout.

What has changed?

Previously, add-to-cart measurement relied on product listing page (PLP) and product details page (PDP) click-through as a proxy. This approach had two key limitations: it missed sessions that landed directly on a PDP without going through a PLP, and it ignored add-to-cart actions that happened on the PLP itself, which is common in grocery and similar verticals. Additionally, event capture broke when stores used different naming conventions, ran Google Analytics 4 (GA4) and Google Analytics Universal (GAU) simultaneously, or loaded the Activity Flow script more than once.

Now, the data-layer plugin addresses these limitations with the following improvements:

• Expanded compatibility to stores using only GAU.
• Cart events are captured regardless of naming convention, including add_to_cart, addToCart, add-to-cart, add_to_cart_v2, and other common variations.
• Automatic filtering of duplicate cart events when GA4 and GAU run simultaneously.
• Elimination of duplicate events caused by multiple Activity Flow script loads.
• Improved reliability of cart event collection without requiring store-specific customizations.

Why did we make this change?

To replace the PLP and PDP proxy with a more accurate conversion signal, we've improved how the Web Script reads cart events from the dataLayer.

This change accounts for direct-to-PDP sessions and PLP-level add-to-cart actions, broadens compatibility across Store Framework, FastStore, headless, and custom storefront implementations, and ensures a single Activity Flow event is generated for each user cart action. It also reduces maintenance effort by supporting new cart event naming conventions without requiring code changes, making the Activity Flow Web Script more resilient to different analytics implementations across storefronts.

What needs to be done?

The cart event capture mechanism depends on cart events being available in the dataLayer, since the Activity Flow Web Script reads them from window.dataLayer to generate Activity Flow events. Therefore, for this feature to work properly, your storefront must expose cart events in the dataLayer.

No extra action is required for stores using VTEX native storefront solutions — FastStore, Store Framework, or CMS Portal (Legacy) — where Activity Flow is installed by default.

If you use a headless storefront, make sure the Activity Flow Web Script is installed and loaded only once per page. Once the script is in place, the improved cart event capture applies automatically.

To learn more about Activity Flow, see VTEX Activity Flow.

Original source

VTEX Sales App Extensibility allows merchants to customize the default assisted-sales journey by rendering components and adding capabilities at predefined slots in the Sales App interface. The feature is available in open beta for all stores that use Sales App.

To support the development and implementation of extensions, merchants and partners can use the VTEX Sales App Extensions Skill, an AI-powered skill that comes with built-in knowledge of the Sales App and the FastStore monorepo.

What changed?

VTEX Sales App Extensibility introduces eight predefined extension points across key contexts of the sales journey:

• Cart and checkout: cart.cart-item.after, cart.cart-list.after, cart.order-summary.after
• Product Detail Page (PDP): pdp.sidebar.before, pdp.sidebar.after, pdp.content.after
• Menu and drawer: menu.item, menu.drawer-content

Extensions can integrate with external APIs and safely interact with data from other applications. The solution is built around three core principles:

• Security: Safer code implementation for developers.
• Stability: Application stability is preserved even when customizations fail.
• Compatibility: Extensions remain compatible with existing customizations.

Common use cases include loyalty program integrations, additional services (such as warranties or insurance), integrations with VTEX solutions outside the default Sales App flow, and consolidation of sales representatives' tasks on a single platform.

What needs to be done?

Implementation of VTEX Sales App Extensibility is handled by merchants and partners. Follow the Sales App extensions implementation guide to get started.

Use the VTEX Sales App Extensions Skill as an AI assistant throughout the definition and implementation of extensions.

Original source

What has changed?

VTEX Sales App Extensibility allows merchants to customize the default sales journey through extensions at predefined extension points in the interface, without having to build solutions from scratch. This feature is available in open beta for everyone using Sales App on VTEX.

To support the development and implementation of extensions, merchants can use the VTEX Sales App Extensions Skill, an AI-powered skill with built-in knowledge of the Sales App and the FastStore monorepo.

VTEX Sales App Extensibility allows you to render components and add features at eight predefined extension points of Sales App. The main goals of this feature are:

• Security: Enhance developers' security when implementing code.
• Stability: Keep the application stable, even when customizations fail.
• Compatibility: Integrate with external APIs and interact with data from other applications while preserving extension compatibility with customizations.

Some use cases for VTEX Sales App Extensibility include integrating with loyalty programs, selling additional services such as warranties and insurance, integrating with VTEX solutions outside the default Sales App flow, and centralizing sales representatives' daily tasks on a single platform.

The images below show the extension points in the sales journey:

• Shopping cart (cart.cart-item.after, cart.cart-list.after) and checkout (cart.order-summary.after):

[image]

• Product details page (pdp.sidebar.before, pdp.sidebar.after, pdp.content.after):

[image]

• Menu (menu.item) and side modal (menu.drawer-content):

[image]

[image]

What needs to be done?

Implementation of VTEX Sales App Extensibility is handled by merchants and partners. To do so, we recommend following the Sales App Extensions implementation technical documentation.

Use the VTEX Sales App Extensions Skill to help with the project's definition and implementation steps.

Original source

We've redesigned the order and checkout configurations page in the VTEX Admin. The configurations are now available in a new, independent experience with a more modern interface and faster loading times, while keeping the same configuration options you already use.

Accessing the page still requires the License Manager resources: Save Order Configuration and Save OrderForm Configuration.

Why did we make this change?

The main advantages of this change are:

• A more modern, responsive interface for managing order and checkout configurations.
• Faster loading and greater stability, as the page now runs as an independent app.
• A more consistent experience, aligned with the evolution of the VTEX Admin.

What needs to be done?

Starting July 22, the beta version of the configurations page will be available to selected VTEX stores. This experience will be gradually enabled over the following weeks, and your existing configurations will be preserved. During the validation period, if you want to go back to the previous version of the configurations page, you can click the Switch to previous version button.

Starting September 1, the new order configurations interface will be the default for all VTEX stores.

Original source

To provide more flexibility and control over post-purchase payment operations, VTEX has launched the Partial payment processing mode.

What has changed?

Previously, post-purchase payment operations (settlements, cancellations, and refunds) were only performed in Total or Hold modes, without the option to perform partial operations (with amounts lower than the order total) directly with the payment provider connector.

With the new Partial mode, each settlement, cancellation, or refund request is automatically sent to the connector, enabling faster financial management, lower operational costs, and a better post-purchase experience for customers. This mode doesn't support split payment transactions.

For more information on how each mode works, see Post-purchase payment operations.

What needs to be done?

This feature is already available for all VTEX accounts. If you want to use the Partial mode in any of the payment connectors configured in your store, contact VTEX Support to request activation in your account.

Before requesting the Partial mode configuration, check with your payment provider to see if the connector you are using supports multiple partial operations.

Original source

Now, you can offer Apple Pay Express Checkout V6 in your VTEX store. This payment method is available for purchases on devices compatible with macOS and iOS, and in Safari and Google Chrome.

The Apple Pay Express Checkout V6 feature is currently in closed beta.

What has changed?

Apple Pay was previously available only for FastCheckout stores. Now stores using Checkout V6 can also use it.

With this update, customers can use an express checkout experience without having to manually complete their information. When you select Apple Pay, your purchase can be confirmed in just a few clicks.

Payment authentication is done directly on the customer device, using Face ID, Touch ID, or password, ensuring a fast, secure, and frictionless journey.

Current limitations

Apple Pay Express Checkout V6 has the following limitations in this version:

• There is no support for installments or promotions from card networks.
• It's not available for scheduled delivery or pickup points. In these cases, customers have to use other payment methods at checkout.

What needs to be done?

The Apple Pay Express Checkout V6 is currently in testing (closed beta). If you want to enable this payment method in your store, follow the steps below:

1. Check with your chosen payment provider to see if they support credit card transactions using the Device Primary Account Number (DPAN). Specific support for Apple Pay is not required. The only requirement is that the provider can process transactions with DPAN.
2. Contact VTEX Support to request the activation of Apple Pay Express Checkout V6 in your store.

Original source

Bug Fix

Versioned Authenticator routes for My Account B2B Buyer Portal (PR: #3398)

FastStore now uses versioned Authenticator API routes for password reset flows. The password reset and authentication start requests now include the v1 segment in the API path, following the expected Authenticator route format.

Stores using FastStore My Account password reset should upgrade to v4.4.0 to avoid issues when unversioned Authenticator paths are deprecated. No configuration changes are required, and no deprecation date has been set at this time.

Improvement

CMS aware cms-sync command (PR: #3406)

The faststore cms-sync command now supports stores using the CMS. Previously, these stores had to run schema generation and upload commands separately. Now, the command identifies the store's CMS setup and automatically runs the appropriate sync flow.

For stores using the CMS, the command includes schema generation and upload in the sync process. It also checks the VTEX CLI version and verifies the authenticated VTEX account before running schema generation.

Stores using the CMS should upgrade to v4.4.0 and run faststore cms-sync instead of separate schema commands. Stores using the Headless CMS (legacy) integration see no workflow change.

Localization feature (Closed Beta)

Sync Intelligent Search locale with URL on navigation (PR: #3405)

FastStore now keeps Intelligent Search queries aligned with the active URL locale during client-side navigation.

Previously, stores using the Localization feature (Closed Beta) could experience stale locale data after switching locales or using browser back and forward navigation. This could cause Product Listing Pages, search results, or shelves to display product information in the wrong locale.

With this update, FastStore derives the search locale from the active route and prioritizes the locale selected in the URL. This helps ensure product names and slugs update correctly after a locale switch.

Stores with localization.enabled should upgrade to v4.4.0 and verify that Product Listing Pages, search pages, and shelves are accessible under locale-prefixed URLs. No configuration changes are required.

CMS-backed My Account for B2B Buyer Portal pages (PR: #3354)

My Account for B2B Buyer Portal pages can now use CMS content. Previously, these pages relied on hardcoded English copy and could not be customized.

This update adds CMS content types and section schemas for My Account for B2B Buyer Portal pages, including profile, orders, order details, user details, security, and unauthorized access. If CMS content is available, My Account for B2B Buyer Portal pages render the published content. If CMS content is empty or unavailable, pages continue to render with default English content.

Merchants can use the CMS to localize labels, reorder sections, and customize order status badges. Stores with localization.enabled should upgrade to v4.4.0 and run the faststore cms-sync in the terminal.

i18n support for My Account for B2B Buyer Portal navigation (PR: #3400)

My Account for B2B Buyer Portal routes now preserve the active locale during navigation and server-side redirects.

Previously, private My Account routes could drop the locale prefix when users navigated between account pages or were redirected on the server side. For example, a user could be redirected from /pt-BR/pvt/account/orders to /pvt/account/orders.

With this update, My Account links, filters, pagination, order details, and server-side redirects preserve the active locale. Price and date formatting also follow the locale from the current route.

Stores with localization.enabled and path-based bindings should upgrade to v4.4.0 and verify My Account navigation, redirects, and formatting under locale-prefixed URLs.

Original source

The new Intelligent Search API v1 is now available for headless integrations at /api/intelligent-search/v1/*. It replaces Intelligent Search API (Legacy) at /api/io/_v/api/intelligent-search/* with HTTP caching, lower latency, and explicit context parameters.

What has changed?

Here is a summary of the key differences between Intelligent Search API (Legacy) and Intelligent Search API v1. See the sections below for full details.

HTTP caching

Responses from most endpoints now include a Cache-Control header, enabling CDN and browser caching for public sales channels. This reduces origin load and improves storefront response times.

Always read the Cache-Control header at runtime to determine cacheability. Don't hardcode cache durations in your integration.

Exceptions:

• Responses containing sponsored products (VTEX Ads) are not cached, preventing ad impressions from being served from a shared cache.
• Private sales channel responses: not cached.

Explicit context: No segment cookie

Intelligent Search API (Legacy) relied on the VTEX segment cookie to fill in locale, sales channel, regionalization, and marketing context. Intelligent Search API v1 does not read the segment cookie. All context must be passed explicitly as query parameters or facets in the URL path.

If your store uses Delivery Promise for headless stores, the following parameters were previously passed via the segment facets string and must now be passed as explicit query parameters on GET Search products (v1), GET List filters for a search (v1), and GET Get pickup point availability for Delivery Promise (v1):

• country, zip-code, and optionally coordinates (buyer's address, the fundamental parameters)
• deliveryZonesHash and pickupPointsHash (pre-computed alternative for faster lookup; hashes expire and require a specific renewal flow, so always have the address available as a fallback)
• pickupPoint

New URL structure

The IO prefix has been removed, underscores in path names have been replaced by hyphens, and /v1 has been added to the path.

New endpoint: Get product

A new GET Get product (v1) endpoint is now available for product detail pages (PDP). Given a known identifier (product ID, slug, EAN, SKU ID, or reference), it returns a single product without going through the search pipeline, resulting in lower latency and better cache-hit rates than GET Search products (v1).

New data returned in product search

Intelligent Search API v1 returns additional and corrected data in products[].items[] on the following endpoints:

• GET Search products (v1) (previously GET Get list of products for a query)
• GET Get product (v1) (new)

Fields that previously returned incorrect or empty values, such as isKit, modalType, and images[].imageText, now return correctly, potentially resolving a known issue.

What needs to be done?

For a step-by-step migration checklist, see Migrating to Intelligent Search API v1.

All new headless integrations must use Intelligent Search API v1.

Intelligent Search API (Legacy) remains available for existing integrations, but its endpoints will be deprecated in a future announcement. We recommend migrating existing integrations as soon as possible.

To access all performance and reliability improvements in Intelligent Search API v1, headless integrations should use the REST API directly. Integrations using Search GraphQL aren't recommended for headless implementations and should be migrated to Intelligent Search API v1.

Related resources

• Intelligent Search API v1
• Intelligent Search API (Legacy)
• Migrating to Intelligent Search API v1

Original source

The Activity Flow SDK for mobile now supports customer interaction event tracking (click, view, and impression) in React Native and Flutter apps. This aligns the mobile SDKs with the web script, so you can measure the full engagement funnel (rendered → seen → clicked) for any component in your app, not just page views and ad events.

What has changed?

Previously, mobile apps supported only page views and ad events. Customer interaction tracking was available on the web via the Activity Flow script.
Now, React Native and Flutter apps support click, view, and impression tracking.

React Native

• Click tracking: Use the new useClickObserver hook to capture tap interactions. It returns an afHandlePress callback to call in your press handler.
• View tracking: Use the new useViewObserver hook to detect when a component is at least 50% visible for 1 second. It returns an afViewRef that can be attached to the target view.
• Impression tracking: Use the new useImpressionObserver hook to record when a component is rendered, regardless of viewport visibility. It re-fires only when the tracked attributes change.

Flutter

• Click tracking: Use the new addClickListener extension method on any widget to capture tap interactions.
• View tracking: Use the new addViewListener extension method to fire a view event when the widget is at least 50% visible for 1 second (per IAB standards). It fires once per app session.
• Impression tracking: Use the new addImpressionListener extension method to record when a widget is built and rendered in the widget tree.

What needs to be done?

To implement interaction event tracking in your app, see the related guides:

• Installing Activity Flow in React Native apps
• Installing Activity Flow in Flutter apps

Original source