VTEX Release Notes

VTEX CX Platform now also identifies WhatsApp contacts by their Business Scoped User ID (BSUID), WhatsApp's business-scoped user identifier. As a result, your conversations and automations keep working even when the contact hasn't shared a phone number.

Interaction by BSUID alone is being rolled out gradually by Meta. Until then, this behavior has been validated in simulated scenarios, and no change is expected in the current WhatsApp channel experience.

What has changed?

Previously, the phone number was the only identifier for a WhatsApp contact in VTEX CX Platform. If a contact didn't share their number, you couldn't receive their messages or send them templates.
Now, the platform automatically resolves the identifier available in each conversation:

• If the contact has a phone number: everything works as before.
• If the contact has only a BSUID: you keep receiving their messages and can send templates normally, with no additional configuration.

The contact's BSUID appears on the contact details page, alongside the other profile information. You can also:

• Request the phone number: agents can invite the contact to voluntarily share their number through a native WhatsApp component. Sharing is optional and only happens if the contact agrees.
• Segment contacts without a phone number: when creating a group in Contacts, select the WhatsApp contacts without phone option to generate a smart group with all contacts that have a BSUID and no phone number. This lets you track that audience specifically.

Why did we make this change?

WhatsApp is evolving its privacy model, and users will be able to interact with businesses using a username, without exposing their phone number. This means the number is no longer a guaranteed identifier. To keep your communication running when this model takes effect, we developed BSUID support in VTEX CX Platform. The key benefits are:

• Uninterrupted communication: incoming conversations and template sends keep working for any contact, regardless of the identifier available.
• Early readiness: your store is already prepared for WhatsApp's identity changes, without depending on a future platform update.
• Compliant profile enrichment: you can ask the contact for their phone number through an official WhatsApp component, respecting the customer's choice.
• Preserved automations: BSUID support is integrated into the same identification layer used by native WhatsApp automations, such as abandoned cart, Pix recovery, and order status.

What needs to be done?

No action is required. Contact identification is handled automatically by VTEX CX Platform, with no need for you to choose between phone number and BSUID.

If you use external systems that rely exclusively on the phone number as the contact identifier, such as CRMs, custom integrations, BI pipelines, or segmentation rules, we recommend planning to adapt those systems to also accept the BSUID.

To learn more about the WhatsApp channel, see WhatsApp: Integration with VTEX CX Platform.

FastStore now keeps interface-only fields out of session and cart requests, restoring validation and Checkout synchronization after shoppers set their location.

This issue affects only FastStore v4.9.0 and v4.9.1.

FastStore now validates sessions and carts correctly after shoppers set their location through the region modal, popover, or slider. This fix restores cart synchronization with Checkout for affected shoppers.

What has changed?

In the affected versions, setting a postal code could save the interface-only hasValidated field in the shopper's session. Because this field isn't part of the session input accepted by the API, subsequent ValidateSession and ValidateCartMutation requests failed with a 500 error. The invalid session remained in IndexedDB, preventing the cart from synchronizing with Checkout until the shopper cleared their browser data.

FastStore now removes interface-only fields (isSessionReady, isValidating, and hasValidated) before sending session data to session validation, cart validation, and reorder requests. The same normalization is applied when updating the shopper's region or storing the session.

Sessions that already contain these fields can validate again without shoppers clearing their browser data. The fields are removed from IndexedDB the next time the session is updated.

Why did we make this change?

Interface state is used only to control storefront behavior and shouldn't be sent as part of the API session input. Keeping these fields separate prevents GraphQL validation errors and ensures that session and cart updates continue to reach Checkout after a shopper changes their location.

What needs to be done?

Follow the instructions in Updating the CLI package version to upgrade to FastStore v4.9.2. No additional configuration is required.

FastStore now returns the original product release date to storefront customizations while keeping PDP structured data compatible with Schema.org.

FastStore now returns StoreProduct.releaseDate in the original format provided by Intelligent Search. This restores compatibility with storefront customizations that consume the field directly while keeping product structured data valid for search engines.

What has changed?

In FastStore versions v4.7.0 through v4.8.x, the API resolver converted StoreProduct.releaseDate to an ISO 8601 calendar date. This conversion was introduced to make the product detail page (PDP) JSON-LD compatible with Schema.org, but it also changed the value returned to every GraphQL consumer. As a result, customizations that expected the original epoch value could stop working.

Now, StoreProduct.releaseDate is returned without modification, as provided by Intelligent Search. ISO 8601 normalization is applied only when FastStore builds the product JSON-LD on PDPs. Therefore:

• Storefront customizations receive the original catalog value.
• Release dates in PDP JSON-LD structured data are normalized to ISO 8601 for Schema.org compatibility.
• Missing release dates continue to return an empty string.

Why did we make this change?

Only the PDP structured data requires an ISO 8601 date. Applying the conversion in the API resolver changed the field for all consumers, including custom storefront code that relied on its original format.

Moving the conversion to the JSON-LD generation keeps product metadata compatible with search engines without changing the value consumed by storefront customizations.

What needs to be done?

Follow the instructions in Updating the CLI package version to upgrade to FastStore v4.9.1.

If you changed a customization in v4.7.0 or v4.8.x to expect an ISO 8601 date, update it to parse and validate the original value returned by the catalog. Do not assume a specific format, because the field may contain an epoch timestamp, another string format, or an empty string.

No additional configuration is required for stores that don't consume StoreProduct.releaseDate directly.

What has changed?

A schema save that triggers a full reindex of a data entity now blocks further schema saves on that entity for 12 hours, which return 423 Locked.

Saving a schema in Master Data with Save schema by name can now apply a temporary reindex lock if the save triggers a full reindex of a data entity.

If a Save schema by name triggers a full reindex, further schema changes via the same endpoint are blocked for 12 hours.

While the lock holds, PUT /api/dataentities/{dataEntityName}/schemas/{schemaName} returns 423 Locked. The response body carries a Message field stating that a reindex is in progress and, when available, the time after which the save can be retried.

The reindex lock does not block document saves.

What needs to be done?

If your integration updates schemas programmatically, handle 423 Locked as an expected response rather than a failure. Retry the save after the time reported in the Message field, or try again later if Message does not report a time.

If you only change schemas manually, no action is required.

Learn more

• Master Data API v2 reference
• Save schema by name

Budget Pacing is available in open beta In VTEX Ads. With this feature, the system automatically redistributes a campaign's budget over the cycle, ensuring the full investment is delivered without the need for manual daily adjustments.

What has changed?

Previously, VTEX Ads campaigns operated exclusively with a fixed daily budget. When a campaign linked to a monthly Insertion Order didn't spend as expected in the first few days, it was necessary to manually recalculate and adjust the budget to restore the delivery pace.

With Budget Pacing, you only need to set one piece of information: the average daily allocation. Based on this amount, the system automatically redistributes consumption across the cycle, speeding up on underconsumed days and slowing down when the campaign is ahead of the expected pace.

The main changes in the interface are:

• Average daily allocation field on the campaign creation and editing screens, with the cycle's total estimated spend automatically calculated and updated in real time.
• Access to the budget consumption report in the campaign details, with pacing status, daily charts, and hourly analysis. The report provides visibility into delivery pace, enabling account managers to proactively report to the client.

Why did we make this change?

Previously, campaigns tied to monthly Insertion Orders were subject to two limitations:

• Underdelivery risk: When consumption fell below expected in the first days of the cycle, the campaign might not deliver 100% of the contracted value by the end of the period.
• Lack of visibility: Account managers didn't have a dedicated report to track consumption pace and proactively report to the client.

What needs to be done?

Budget Pacing is activated by the VTEX internal team per publisher. To request activation, contact the VTEX AdOps team.

After activation, all new publisher campaigns will automatically operate with Budget Pacing. Campaigns with an already set end date will remain on the fixed daily budget model until closure. Active always-on campaigns will automatically migrate at the start of the next 30-day cycle.

To understand in detail how the mechanism works, see the Budget Pacing tutorial.

Learn more

• Budget Pacing
• Monitor budget consumption

FastStore preview URLs no longer require a redeploy to stay usable. Idle previews are automatically deactivated and reactivate on the next access.

FastStore preview deploys now use an inactivity-based lifecycle instead of a fixed expiration window. Preview URLs remain usable for longer, eliminating the need to redeploy just to bring them back.

What has changed?

Previously, preview URLs were discarded a few days after creation, regardless of usage, and had to be redeployed to work again.

Now, a preview URL is automatically deactivated only after 12 hours of inactivity. Accessing the URL again automatically reactivates it:

• The first request to a deactivated preview shows a loading screen while the preview wakes up. The page refreshes on its own, and the storefront loads normally after a few seconds.
• If a preview can no longer be reactivated, an expired page is shown instead, and the branch needs to be redeployed to generate a new preview.

For more information, see Preview availability in the FastStore WebOps - Dashboard guide.

Why did we make this change?

This improvement lets you keep using a preview URL for as long as you need it, simply by accessing it, instead of losing it after a fixed number of days and having to trigger a new deploy.

What needs to be done?

This behavior is automatic and requires no configuration. However, if you run automated tests against preview URLs, add a retry to your test setup: a request made right after a period of inactivity may return an HTTP 202 Accepted status while the preview wakes up, before returning 200 OK once the storefront is fully available.

FastStore v4.8.0 adds cart-drawer recommendations for higher conversion, safer BFF extensions, and more reliable builds on Windows, plus stronger SEO for localized stores

FastStore v4.8.0 helps merchants increase average order value with recommendations in the mini cart, provides developers with safer, faster ways to extend the BFF and run the CLI, and improves storefront stability under bot traffic and in multilingual SEO. Shoppers get a more polished My Account experience for B2B Buyer Portal Cards, and teams on Windows or in monorepos spend less time on opaque build failures. See the sections below for details.

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

Features

Mini cart recommendation shelf (PR: #3466 )

Adds an optional CartRecommendationShelf inside the cart drawer, between cart line items and the order summary. Merchants configure the shelf on the Cart Sidebar CMS group with a display toggle (off by default), campaign VRN, title, carousel settings, and product-card options. The shelf reuses recommendation shelf patterns and hides when the cart is empty.

Merchants can promote complementary products at the moment shoppers are ready to buy, without custom storefront code. Shoppers discover relevant items without leaving checkout flow, which supports higher conversion and basket size. For more information, see the Displaying recommendations in the mini cart section.

Build safer custom BFF routes with VTEX ID authentication helpers (PR: #3481 )

Exports two helpers that already exist in the BFF but were not part of the public package entry: validateUserAuthentication(ctx) (calls commerce.vtexid.validate() and throws UnauthorizedError / ForbiddenError on failure) and getAuthCookie(ctx) (reads the VTEX ID auth cookie from the request context).

Teams building custom BFF routes spend less time reimplementing VTEX ID checks and reduce the risk of auth bugs that expose data or block legitimate buyers. Extensions behave consistently with the platform BFF. Upgrade @faststore/api to v4.8.0 and import the helpers from @faststore/api in server-side extension code. For more information, see the Authentication in API extensions.

Bug Fixes

Stop forwarding unvalidated ni output to the shell in the CLI (PR: #3422 )

Validates the stdout of ni package-manager detection in getPreferredPackageManager() before callers interpolate it into shell commands. Previously, unexpected output could produce opaque /bin/sh: syntax error failures during faststore commands with no log context tying the error to package-manager detection.

Developers and CI pipelines get clearer, faster resolution when builds fail—you are less likely to lose hours chasing a generic shell error unrelated to your store code. No configuration changes are required after upgrading to v4.8.0.

Resolve the next binary from @faststore/core (PR: #3454 )

Introduces resolvePackageBin() so .faststore scripts invoke the next binary shipped with @faststore/core instead of whichever copy wins in a hoisted monorepo node_modules/.bin (for example, an older major that does not support next build --webpack).

Partners and merchants using monorepos can ship FastStore on the same repo layout as the rest of their stack without surprise next build failures, so releases stay on schedule. After upgrading to v4.8.0, rebuild your project.

Export Resolver, GraphqlContext, and helper types from the public @faststore/api entry (PR: #3474 )

Re-exports GraphQL resolver typings (Resolver, GraphqlContext, and related VTEX platform types) from packages/api/src/index.ts so custom BFF resolvers type-check under strict without reaching into internal paths. Includes compatibility adjustments to keep the public Resolver type aligned with v3 expectations.

Teams get faster, safer development: IDE autocomplete, and compile-time checks catch resolver mistakes before production, and upgrades break fewer custom integrations. Import types from @faststore/api and remove fragile deep imports from internal modules.

Generate GraphQL types when the project path contains spaces (PR: #3476 )

Quotes and escapes filesystem paths in the GraphQL code-generation step so faststore build, faststore dev, and faststore generate succeed when the store lives under directories with spaces (for example, My Store).

Any developer can clone a store into a normal user folder on Windows or macOS without being forced to rename paths or maintain a second copy of the project just to run the CLI.

Keep store Storybook stories and Jest mocks out of the .faststore type-check (PR: #3477 )

Extends storefront copy rules so next build type-checking inside .faststore excludes store-level Storybook stories and Jest mock files.

Teams that document components in Storybook or use mocks beside production code can ship production builds without stripping dev-only files or fighting TypeScript errors unrelated to the live storefront.

Normalize outputFileTracingRoot to forward slashes on Windows (PR: #3484 )

Converts process.cwd() to forward slashes before writing outputFileTracingRoot into the generated next.config.js, preventing JavaScript escape sequences (such as \f) from corrupting the config when paths contain backslashes on Windows.

Windows-based developers get parity with macOS/Linux—production builds complete reliably rather than failing on config parse errors unrelated to store business logic.

Keep Yarn 1 from hoisting an incompatible @inquirer/type into the CLI (PR: #3459 )

Adjusts @faststore/cli dependencies and install behavior so Yarn 1 store installs do not hoist @inquirer/type@3 over @inquirer/core@9, which removed CancelablePromise and crashed builds after regenerating yarn.lock.

Yarn 1 stores regain predictable faststore dev and faststore build runs after lockfile updates, with fewer blocked local development sessions and failed deploys. Upgrade and reinstall dependencies if interactive CLI prompts previously crashed at build time.

Stop retrying upstream HTTP 429 responses in GraphQL client hooks (PR: #3453 )

Updates onErrorRetry in the GraphQL SDK so client-side hooks never retry responses with status 429, while preserving SWR’s default retry behavior for other error statuses.

Stores see more stable performance when crawlers or bursts of traffic hit rate limits, fewer wasted API calls, less load on VTEX services, and a lower chance of degraded checkout or catalog pages for real shoppers.

Forward contentSource.project as --storeId in CMS cms-sync (PR: #3482 )

Passes contentSource.project through to vtex content upload-schema as --storeId in the CMS cms-sync flow. Previously, the value was used only for the account preflight check, which required interactive toolbelt prompts during CI or headless runs.

Merchants automate CMS schema sync in CI and onboarding scripts without manual prompts, so content goes live faster, and human error from picking the wrong store ID drops. Confirm discovery.config defines the correct contentSource.project for your CMS workspace.

Localization feature (Closed beta)

Point localized canonical URLs and hreflang at the rendered locale (PR: #3470 )

Fixes SSR localization URL resolution so getStoreURL() no longer infers locale from window.location during server render. Collection and listing templates receive binding-aware URLs, and PLPs emit hreflang alternates for localized routes.

Multilingual stores improve organic search signals—search engines index the correct locale URLs, and shoppers land on the right language version from SERPs and shared links. Merchants reduce duplicate content and wrong-locale ranking issues. After upgrading to v4.8.0, spot-check canonical and hreflang tags on a few localized PLPs and landing pages.

My Account for B2B Buyer Portal (Closed beta)

Align the saved-cards list with the design reference (PR: #3487 )

Updates MyAccountListCards layout and styles so the Personal and Shared saved-card listings match design review for spacing, typography, and empty states introduced in v4.7.0.

B2B buyers see a clearer, more trustworthy payment experience when managing personal and shared cards—fewer layout surprises and empty states that look broken. No CMS or configuration changes beyond upgrading to v4.8.0.

The Delivery Promise Suggestions API now offers the Get delivery zones and pickup points hashes endpoint, which returns both the deliveryZonesHash and the pickupPointsHash in a single response. The two previous hash generation endpoints are now deprecated.

The Delivery Promise Suggestions API now offers a new operation, Get delivery zones and pickup points hashes (POST /api/logistics-shipping/zones/_search), documented in the API Reference. It returns the delivery zones and the pickup points available for a given location, along with both hashes that represent the shopper's fulfillment context.

What has changed?

• The new operation is POST /api/logistics-shipping/zones/_search, listed under the Logistics shipping tag. The request body takes zipCode, coordinate (with latitude and longitude), and country (ISO 3166-1 alpha-3), all required.
• The response returns deliveryZonesHash and pickupPointsHash in a single call, plus deliveryZoneIds and pickupDistances (with pickupId, distance in kilometers, and pickupName).
• This is now the recommended endpoint for generating the hashes required by Get delivery suggestions, Search delivery suggestions, and the Intelligent Search API endpoints.
• Both hashes have a time to live (TTL) of 30 minutes. After that period they expire, and requests sent with an expired hash may be rejected or return invalid responses. This expiration is now documented in the new endpoint's description and in the descriptions of the deliveryZonesHash field and the pickupsHash query parameter of the delivery suggestions endpoints.
• The Search delivery zones (POST /api/logistics-shipping/delivery-zones/_search/v2) and Search pickup points (POST /api/logistics-shipping/pickuppoints/_search) endpoints are now marked as deprecated in the API Reference. They still work, but their use is no longer recommended.

What needs to be done?

No immediate action is required because the deprecated endpoints keep working, and no existing endpoint has changed its behavior.

Still, we recommend that integrations that generate the fulfillment context hashes migrate to POST /api/logistics-shipping/zones/_search, replacing the two separate calls to the deprecated endpoints with a single call.

Because the hashes expire after 30 minutes, we also recommend calling this endpoint as close as possible to the moment the hashes are used, and handling the expired hash scenario by requesting new ones. There is no penalty or side effect of regenerating them.

Learn more

• Delivery Promise Suggestions API reference.
• Get delivery zones and pickup points hashes in the API Reference.
• Intelligent Search API reference.

You can now track WhatsApp automation execution for your store directly in the VTEX Admin, in the new Logs tab of VTEX CX Platform automations. Every send attempt is logged with template, date, contact, order, amount, and status, allowing you to confirm if a message was sent and understand why it was ignored or failed.

What has changed?

Previously, to find out if a WhatsApp automation had sent a message or why it had not been sent, you had to contact support.

Now, WhatsApp automations such as WhatsApp Cart Recovery, WhatsApp Order Notifications, and WhatsApp Payment Recovery have the Logs tab, which displays all executions in the interface. In each record, you'll find:

• Template: message template used in the send, such as Abandoned Cart.
• Contact: customer's WhatsApp number.
• OrderForm ID: order or cart ID.
• Amount: order or cart associated with the send.
• Status: execution result, which can be Sent, Delivered, Read, Processing, Ignored, or Error.
• Date: execution date and time.

You can search for contacts or order IDs and filter records by period, template, and status. When you expand a record, you see a result summary and the View JSON button, which displays the complete execution crawling.

Why did we make this change?

We developed the Logs tab so you can access information about automations without depending on support. This feature is available to all VTEX CX Platform users in the VTEX Admin. Its key benefits are:

• Complete visibility: all executions are recorded in a single list, with the main data for each send.
• Independent diagnostics: the search, filters, and JSON details allow you to quickly identify the cause of a failure or ignored send.
• Email export: you can export logs and receive them via email for analysis or sharing.

What needs to be done?

No action is required to view WhatsApp logs in VTEX CX Platform. The update is already available in the VTEX Admin for all stores. To view logs, go to Storefront > VTEX CX Platform > Dashboard, click Settings, open a WhatsApp automation, and select the Logs tab.

To learn more about VTEX CX Platform, see Introduction to CX.

Intelligent Search received a set of improvements that increase the relevance and accuracy of search results, along with a fix for a bug in the English language parser. These improvements aren't applied automatically. To enable any of them for your account, contact VTEX Support.

What has changed?

Minimum result coverage for facets

You can now hide facets that affect only a small share of search results. Large catalogs often contain facets created from specifications shared by only a few products, cluttering the facet panel with low-coverage options.

With minimum coverage enabled, facets in which no option reaches the defined minimum percentage of total search results are automatically hidden. You can exclude specific facets from this rule so they're always displayed, regardless of the configuration.

Consider a search for "shirt" that returns 1,000 products, with minimum coverage set to 5%:

• The Color facet covers 1,000 products (100%) and is displayed.
• The Size facet covers 600 products (60%) and is displayed.
• The Fabric facet covers only 30 products (3%) and is automatically hidden because its options don't reach the minimum percentage.

Learn more in Search configuration.

Keyword generation from any product specification

In addition to the product name and brand, you can configure product specifications to generate keywords. When a specification is set to generate a keyword, the values entered are treated as product keywords and given the same weight as keywords extracted from the product name or brand.

This improvement is especially useful for catalogs where information relevant to search is recorded in specifications rather than in the product name, for example, when the name doesn't describe the item's type, function, or other core attribute.

Consider a search for "frost free":

• Duplex Refrigerator 400L (specification "Defrost technology": Frost Free, set to generate keywords) has high relevance, since the specification value matches the search and generates the same bonus as a keyword match, even if the term doesn't appear in the product name.
• Refrigerator 400L (specification "Defrost technology": Cyclic) has low relevance, since neither the name nor the specification value matches "frost free".

Learn more in How search results relevance works.

Special character handling

The processing of symbols such as ®, @, and & in search has been improved. When you enable this feature, these characters are ignored during indexing, allowing products with symbols in their names to be found even when customers leave those symbols out of their search queries.

For example, the product Brand® Multipurpose & Copier Bond Paper can be found when customers search for brand bond paper.

Learn more in Search behavior.

Bug fix: English language analyzer stemming

Intelligent Search uses a language analyzer to normalize search terms, unifying singular and plural forms of the same word into a single stem. For example, in English-language stores, a search for sneaker also returns products that contain sneakers.

We fixed stemming inconsistencies in the English language analyzer for terms such as sticks, sharpies, its, bags, boards, books, bowls, cards, crackers, dividers, games, glue-sticks, k-cups, knives, nuts, rolls, shelves, and supplies, whose plural forms weren't correctly mapped to the singular stem. This fix is available only for accounts operating in English.

Learn more in Search behavior and in How search results relevance works.

What needs to be done?

None of the improvements listed are applied automatically. To enable any of them in your account, contact VTEX Support and specify which improvement you want to enable. The stemming fix is available only for accounts operating in English.

Features

Recommendation session gated by discovery feature flag (PR: #3449)

Restores experimental.enableRecommendations in discovery.config so Layout can start the VTEX Recommendations personalization session on every page when the flag is enabled, without scanning CMS page data. When the flag is off (default), any mounted Recommendation Shelf starts the session as a fallback while userId is missing, in parallel with cookie retry. This release removes the CMS Enable recommendations? toggle from the Recommendation Shelf schema.

Stores get a clearer, store-wide way to turn recommendations on or off, and shelves can still load personalized products on the first visit without an extra CMS toggle per shelf. Stores that previously enabled the session through the CMS property should set experimental.enableRecommendations: true in discovery.config instead. With the flag off, mounting a Recommendation Shelf on a page is enough to trigger the fallback when no user id is available yet.

Bug Fixes

Correct item videos field casing in Search API types (PR: #3447)

Renames the Intelligent Search item field from Videos to videos in ProductSearchResult and keeps Videos as an optional deprecated alias for backward compatibility.

Custom integrations and storefront code that read product video URLs from Search results can rely on consistent, standard field naming. Prefer videos in new or updated code; the deprecated Videos field will be removed in a future major version. No action is required if your store does not consume video URLs from Search API types directly.

Separate hreflang slugs from locale-switch navigation (PR: #3462)

Introduces defaultLocaleSlug on StoreProduct for locale-selector navigation fallback and limits otherLocales hreflang entries to slugs registered in the catalog's availableLinkIds. Intelligent Search linkText is no longer reused as an hreflang alternate when a localized slug is missing.

Shoppers switching locales land on working product URLs instead of broken links, and search engines receive accurate hreflang annotations that do not point to pages that return 404. Stores with the Localization feature enabled should verify alternate-locale links and locale-selector behavior on PDP after upgrading.

Make PDP product JSON-LD Schema.org compliant (PR: #3465)

Normalizes StoreProduct.releaseDate to an ISO 8601 calendar date regardless of whether Intelligent Search returns epoch milliseconds, epoch seconds, or date strings. PDP JSON-LD now omits empty gtin, mpn, releaseDate, and offers fields instead of publishing blank values, and offer prices are formatted for Schema.org compliance.

Product pages send cleaner structured data to search engines, which can improve rich-result eligibility and reduce validation warnings in tools such as Google Search Console. Upgrade to v4.7.0 and rebuild; no store configuration changes are required.

Resolve redirect matcher module explicitly (PR: #3467)

Changes the local redirect matcher import to src/customizations/src/redirects/index so a store's src/redirects.json file cannot shadow the matcher function during bundling. When the exported matcher is not a function, FastStore logs a warning once and falls back to the platform redirect lookup instead of silently returning null and serving 404.

Shoppers reach the correct destination when Admin redirect rules apply, even if the store also keeps a src/redirects.json file as documented. Stores using both experimental.enableRedirects and src/redirects.json should upgrade to restore redirect behavior. Custom redirect overrides via src/redirects/index.ts continue to work as before.

My Account for B2B Buyer Portal

Gate Cards route and sidebar entry on organization membership (PR: #3463)

Adds the Cards route to ROUTES_ONLY_FOR_B2B_MEMBERS and redirects buyers without a unit or contract association to /pvt/account/404 before calling the Saved-cards service. The sidebar entry is hidden for shoppers with no organization association.

Buyers who can't use saved cards no longer see a Cards menu item or reach a page that returns an error or shows an empty, unusable tab. Organization members retain full access. useAdHocCard continues to control Personal-tab rendering only within the page. No configuration changes are required beyond upgrading to v4.7.0.

My Account for Buyer Portal B2B Cards — Personal and Shared listing (PR: #3443)

Adds a My Account Cards page at /pvt/account/cards with CMS-driven sections for listing personal and shared saved cards. The feature introduces GraphQL queries and resolvers for saved-card data, a MyAccountListCards component with Personal and Shared tabs, and CMS schemas for the new account page and list section. Buyers with the required organization access can view and manage their saved payment cards in one place-personal cards and shared cards on separate tabs, without custom storefront code. After upgrading to v4.7.0, sync the My Account CMS schemas, publish the Cards content type and sections in the CMS via Admin, and ensure eligible buyers have the required B2B organization association. Review sidebar visibility and page gating together with PR #3463.

Restore Order Details layout and first-paint rendering in My Account (PR: #3464)

Adds a skipLazyLoading option to RenderSectionsBase for authenticated My Account pages so CMS sections render on first paint instead of behind lazy-loading placeholders. Order Details grid CSS now targets CMS section wrapper classes rather than nested card data attributes, and server-side props omit undefined orderStatusLabels so pages without CMS order-status content serialize correctly.

Buyers opening an order in My Account see the full order layout immediately—status, payment, delivery, and summary sections in the correct grid—instead of placeholders or a broken two-column layout. Upgrade to v4.7.0; no CMS or theme changes are required.

When a search doesn't find a single product matching all the searched terms, Intelligent Search returns results that match any of the words, an "OR search". We've improved how these OR search results are ranked.

What has changed?

OR searches account for about 5% of all searches, reaching 15% in some stores. Previously, OR search results were ranked mainly by the number of individually matching words, which could place unrelated products above those the customer was actually looking for.

Now, OR search results are ranked by weighting how frequently each matched word appears in the product and how rare that word is in the catalog, instead of simply counting how many words matched. Rarer and more distinctive words, such as a product name, weigh more than common words, such as a unit of measure, bringing the most relevant products to the top.

For example, a search for "painkiller ibuprofen 200 tablets" that falls back to OR now prioritizes products with "ibuprofen", instead of unrelated items like "200-tablet organizer", which also matches "200" and "tablets".

Why did we make this change?

This change makes OR search results more relevant to what the customer is actually looking for, reducing the chance that an unrelated product appears above one that better matches the search intent.

What needs to be done?

No action is required. This ranking improvement is automatically applied to all stores using Intelligent Search.

For more details, see:

• Relevance
• Search behavior

The VTEX Ads API now offers a new operation, Get product results by campaign (GET /product/results), documented in the API Reference. It returns performance metrics for each SKU linked to a campaign, aggregated over an inclusive date range.

What has changed?

• The new operation is GET /product/results (with campaign_id as a query parameter), listed under the Reports tag.
• Each item in the response carries product identity fields, including product_sku, which identifies the product, and performance metrics, including impressions, clicks, and conversions_value.
• Metric values are returned as numeric strings, not as numbers.
• The start_date and end_date parameters are inclusive and both default to the current date when omitted, so a call without them returns data for that date only.
• Results are paginated and sorted with the page, quantity, order_by, and order_direction parameters. Setting count=false returns a bare array of products instead of the total, pages, currentPage, and data envelope.
• This operation returns results per product (SKU) for one campaign, unlike Get ads performance report, which returns results per ad across campaigns, and unlike Get campaign details, which returns campaign-level totals.

What needs to be done?

No action is required for existing integrations, because this is a new endpoint and no existing endpoint changed behavior.
To adopt it, call the operation with the campaign UUID in the campaign_id query parameter, authenticating with the same X-App-Id and X-Api-Key headers used by the other Reports endpoints.

Learn more

• Exporting ads reports guide, for general Reports context.
• VTEX Ads API reference.
• Get product results by campaign in the API Reference.

VTEX launched a conflict detection layer in the Intelligent Search synonym creation and editing flow, indicating when a term is already covered by an existing rule.

What has changed?

• When creating or editing a synonym, Intelligent Search validates the terms entered against all synonyms already registered in the store.
• If a term is already covered by another rule, a notification highlights the overlap and directs you to the Conflicting synonyms page, where you can review, edit, or delete each conflicting synonym individually.
• When you click Save, a confirmation window identifies the conflict and asks you to confirm the registration or edit before proceeding.

Why did we make this change?

In stores with extensive synonym databases, it was common to recreate synonyms that already existed without realizing it, duplicating entries in the list and making synonym management more difficult over time.

What needs to be done?

No action is required. Synonym conflict detection is available for all stores using Intelligent Search. To learn more, see Creating synonyms.