Skip to main content

14 posts tagged with "API"

Catalog Search highlighting, facet value search, and ranking settings

MINOR Catalog Search highlight settings

Search profiles now control how matched words are highlighted in search hits, so highlights match your storefront's markup and show the right amount of each field.

What's New?

  • highlight_settings.fields - Choose which fields are highlighted, including fields the profile does not query
  • highlight_settings.full_fields - Return the whole marked-up value of chosen fields. The highlight_full_fields request parameter overrides it per request
  • highlight_settings.start_tag and end_tag - Set the tags wrapped around matched words. Defaults are <mark> and </mark>
  • highlight_settings.snippet_threshold and context_num_tokens - Control when a long field is trimmed to a snippet and how many words are kept either side of each match

For details see:

MINOR Catalog Search facet value search

Search within the values of a facet, so storefronts can offer a searchable filter list for facets with many values, such as brands.

What's New?

  • facet_query request parameter - Returns only the values of one facet_by field that match the text, each with its count and a highlighted label
  • facet_settings.query_num_typos - Set how many typos a facet query corrects, from 0 to 2. Defaults to 2

For details see:

MINOR Catalog Search ranking settings

Search profiles now expose two relevance ranking signals, and a new guide explains how relevance, boosts, sorting, and pins combine into the final result order.

What's New?

  • ranking_settings.prioritize_exact_match - Rank products whose field contains only the query words above longer matches. On by default
  • ranking_settings.prioritize_token_position - Rank products whose field matches a query word nearer the start of the field higher. Off by default
  • How Ranking Works guide - Covers the relevance signals, text match types, boost scores, and request sort_by

For details see:

Removed advanced promotion usage filtering (cm_search) in standard Promotions

MINOR Removed cm_search advanced promotion usage filtering in standard Promotions

As announced on July 8, 2026, the advanced promotion usage filtering enabled by passing the EP-Public-Search-Type: cm_search header to the GET /v2/promotions endpoint has been removed.

What's Changed?

  • EP-Public-Search-Type: cm_search is no longer supported - Requests to GET /v2/promotions that include this header now return a 400 Bad Request error
  • Advanced usage filter attributes removed - promo_name, promo_status, code_code, order_id, order_customer_email, and the other advanced usage filter attributes are no longer available on this endpoint
  • Standard filtering is unaffected - Filtering promotions with eq(code,...) on GET /v2/promotions continues to work as before

For details see:

Subscriber Pause and Resume, and Proration Refunds

MINOR Subscriber Pause and Resume

If the pricing option allows it, subscribers can now pause and resume their own subscriptions.

What's New?

  • Self-service pause and resume - The can_pause and can_resume pricing option fields now control subscriber pause and resume. A merchandizer can always pause or resume a subscription
  • Who paused a subscription - The new paused_by field records who paused the subscription: subscriber, merchandizer, or dunning. Only merchandizer, store, or organization-scoped callers can see this field
  • Dunning pauses stay with the merchandizer - A subscriber cannot resume a subscription that dunning paused or suspended. Subscriptions cannot tell who paused a subscription before this release, so a subscriber cannot resume those either. A merchandizer must resume these subscriptions

For details see:

MINOR Proration Refunds for Negative Prorations

A plan or pricing option change that results in a negative proration can now issue a refund instead of being rejected. A proration is negative when the credit for the unused time on the old plan is more than the cost of the new plan.

What's New?

  • Configurable per proration policy - To allow proration refunds, turn on Allow automatic refunds for negative prorations in Commerce Manager, or set allow_negative_proration_refund to true through the API. The default is false, so existing proration policies continue to reject negative prorations
  • Automatic gateway refund - If a proration policy allows refunds, Subscriptions refunds the negative amount through the payment gateway. The refund is against the payment for the previous invoice
  • Refund details on the subscription - The new last_refund_id and last_refund_amount fields show the most recent proration refund for a subscription
  • Preview the refund - The proration preview now returns would_refund and refund_amount. It also returns the new rejection reasons refund_not_possible and refund_disallowed_by_policy. The preview no longer returns the negative_amount rejection reason

For details see:

Removed per_application promotion codes in Rule Promotions

MINOR Removed per_application promotion codes in Rule Promotions

As announced on June 16, 2026, the per_application value for the consume_unit field has been removed when creating promotion codes for Rule Promotions.

What's Changed?

  • consume_unit: per_application is no longer supported - Requests that create Rule Promotion codes with per_application, either directly or through a bulk code generation job, now return a 422 Unprocessable Entity error; set consume_unit to per_checkout or omit the field to use the default
  • Existing codes are retained - Promotion codes already created with consume_unit: per_application continue to work as configured
  • Rule Promotions only - This change applies only to Rule Promotions. Promotion codes for standard (V1) Promotions are not affected

For details see:

Order shipping group events available to webhooks and integrations

MINOR Order shipping group events

Integrations can now observe changes to order shipping groups. Two new observable events are available for webhooks and message queue integrations.

What's New?

  • order-shipping-group.created - Triggered when a shipping group is added to an order, including shipping groups created at checkout from a cart with shipping groups
  • order-shipping-group.updated - Triggered when an order shipping group is updated, for example a change to its shipping address, tracking reference, or delivery estimate
  • Order item linkage - The delivered shipping group payload includes relationships.items, identifying the order items the shipping group applies to

For details see:

Cart item custom fields returned in cart include responses

MINOR Cart item custom fields in include=items responses

Retrieving a single cart with include=items now returns each item's custom fields, the same data you get from Get Cart Items. Storefronts can read a cart and its fully described items in one request instead of two.

What's New?

  • Consistent item data - Fields defined on the cart_items flow now appear on every item under included.items in GET /v2/carts/:id?include=items, exactly as they do in GET /v2/carts/:id/items
  • Fewer requests - Storefronts that called Get Cart Items only to read item custom fields can drop that call
  • No change without a flow - Stores that have not defined a cart_items flow see no difference in the response

What's Changed?

  • Cart event payloads - cart.created and cart.updated events delivered to webhooks and message queues are built from this same cart response, so the items in those payloads now carry the same custom fields. The change is additive; existing keys are unchanged
  • Payload size - Each field on the cart_items flow adds one key to every included item, null when unset. SQS queues cap messages at 256 KiB and elide included resources above that limit, so stores with a wide cart_items flow and large carts may want to check their headroom

This applies to single-cart reads only. The cart list endpoint, orders, and quotes are unchanged.

For details see:

Subscription Proration Previews and Pending Cancellation

MINOR Proration Preview Endpoint

You can now preview the cost impact of a subscription plan or pricing option change before submitting it, so subscribers can see what they'll be charged or refunded ahead of time.

What's New?

  • Proration preview endpoint - Compute the proration amounts a prospective plan or pricing option change would produce, without persisting anything or affecting billing
  • Clear rejection reasons - A response with would_prorate: false isn't an error - it tells you why the change wouldn't result in a proration (for example, no_change or negative_amount)

For details see:

MINOR Cancel Pending Subscriptions Before Go-Live

Subscriptions that haven't yet reached their go_live_after date can now be canceled directly, without needing to wait for the subscription to become active.

What's New?

  • Immediate cancellation for pending subscriptions - Canceling a pending subscription (one with no invoices yet) is always immediate, since there's no billing period in progress to defer to
  • Self-service for subscribers - Subscribers can cancel their own pending subscription without needing to set the cancel_immediately flag

For details see:

Catalog Search query-triggered boost and bury with search rules

MINOR Catalog Search query-triggered boost and bury with search rules

Catalog Search now supports search rules in rule groups so merchandisers can boost, bury, pin, hide, rewrite, or filter results when a shopper query or browse listing matches a trigger.

What's New?

  • Search rule groups - Named containers for query-time merchandising rules
  • Search rules - Exact, contains, and browse triggers with boost/bury, pin, hide, query rewrite, and rule filter actions
  • Profile rule_groups - Attach ordered rule group IDs to a search profile to activate the rules engine
  • Ordering controls - execution_order within a group and stop_after_match across the profile pipeline
  • matched_rules on search results - See which rule and rule group IDs matched a full search (not autocomplete)

What's Changed?

  • Always-on profile boosts remain available for every search on a profile; search rules apply only when a trigger matches
  • Autocomplete does not evaluate search rules

For details see:

Catalog Search Indexed Fields replaces Searchable Fields for schema discovery

MINOR Catalog Search Indexed Fields replaces Searchable Fields for schema discovery

Use Indexed Fields to list every field in the search index — including numeric, boolean, and date fields — with flags for how each field can be used.

What's New?

  • GET /pcm/catalogs/search/indexed-fields - Returns all exposed indexed fields of every type
  • searchable and filterable flags - See whether a field can be used as a full-text query field and in filter expressions
  • Guide coverage - List Indexed Fields in Setting Up Catalog Search, with links from filtering, faceting, and sorting guides

What's Changed?

  • GET /pcm/catalogs/searchable-fields is deprecated - Prefer Indexed Fields. Searchable Fields returns only text query fields and does not cover fields needed for filtering and sorting
  • Searchable Fields remains available for existing integrations; migrate to Indexed Fields for complete schema discovery

For details see:

Deprecation of with_tax and without_tax attributes in Orders filtering

MINOR Deprecation notice of with_tax and without_tax attributes when filtering Orders

As of July 22, 2026, filtering orders using the with_tax and without_tax attributes on the GET /v2/orders endpoint is deprecated. This capability will be removed on October 19, 2026.

What's Changed?

  • Deprecated as of July 22, 2026 - Requests to GET /v2/orders?filter= using the with_tax and without_tax attributes continue to work during the deprecation period, but we recommend removing any dependency on these filters now
  • Removed on October 19, 2026 - After this date, requests to GET /v2/orders?filter= filtered using the with_tax and without_tax attributes will return an error

For details see:

Catalog rules can specify a search profile for shopper segments

MINOR Catalog rules can specify a search profile for shopper segments

Catalog rules can optionally include a search profile so shopper search follows the same segment as catalog and pricing — without hard-coding search_profile in your storefront.

What's New?

  • Optional search_profile_slug on catalog rules - Attach a search profile when configuring the rule for an account, customer, channel, or context tag
  • Automatic profile on shopper search - Matching shopper search and multi-search use that profile for filters, ranking, and related search behavior; a valid rule slug takes precedence over the search_profile query parameter
  • EP-Search-Profile response header - See which profile was applied (SYSTEMS_DEFAULT_PROFILE when the built-in default is used)
  • Price and assortment together - Use the same rule for price books and searchable assortment (for example a reseller-only category filter on the profile)

What's Changed?

  • Shopper search profile resolution - Catalog rule slug (when valid) → search_profile query parameter → tenant default → built-in default
  • Admin search unchanged - Explicit catalog/release search does not apply catalog rule profiles
  • Safe fallthrough - An invalid or stale rule slug does not fail the search; Catalog Search falls through to the next resolution source

For details see:

Upcoming deprecation of advanced promotion usage filtering (cm_search) in standard Promotions

MINOR Upcoming deprecation of cm_search advanced promotion usage filtering in standard Promotions

As of July 8, 2026, the advanced promotion usage filtering enabled by passing the EP-Public-Search-Type: cm_search header to the GET /v2/promotions endpoint is deprecated. This capability will be removed on October 6, 2026.

What's Changed?

  • Deprecated as of July 8, 2026 - Requests to GET /v2/promotions with the EP-Public-Search-Type: cm_search header continue to work during the deprecation period, but we recommend removing any dependency on this header now
  • Removed on October 6, 2026 - After this date, the EP-Public-Search-Type: cm_search header and its advanced usage filter attributes (such as promo_name, promo_status, code_code, order_id, and order_customer_email) are no longer supported on this endpoint
  • Standard filtering is unaffected - Filtering promotions with eq(code,...) on GET /v2/promotions continues to work as before

For details see:

Catalog Search: relevance scores, synonym tuning, and date field faceting

MINOR Text match relevance scores on search results

Search hits now return a breakdown of how their text relevance score was derived, giving merchandisers a window into ranking decisions for debugging and relevance tuning.

What's New?

  • text_match_info on each hit - Every hit includes the overall relevance score plus additional signals such as best_field_score, best_field_weight, fields_matched, tokens_matched, num_tokens_dropped, and typo_prefix_score
  • Diagnose ranking - Use these signals to understand why one product ranks above another, or to build custom relative metrics for relevance evaluation
  • Internal ranking signals, not display metrics - Scores are not normalized to a 0–100 scale and are only comparable within the same result set, so they are intended for debugging rather than shopper-facing "match %" display

For details see:

MINOR Synonym tuning settings on search profiles

Search profiles now expose a dedicated synonym_settings object so you can control how synonym matches are ranked and resolved at search time, independent of typo tolerance settings.

What's New?

  • Demote synonym matches - Set demote_synonym_match to rank results matched via a synonym below direct (non-synonym) matches
  • Prefix synonym resolution - Set synonym_resolution_allowed_on_prefix to allow incomplete (prefix) query tokens to resolve to synonyms at every token position
  • Typo-tolerant synonym resolution - Set number_of_typos_allowed_when_resolving_synonyms (0, 1, or 2) so misspelled terms can still trigger a synonym expansion; this setting has moved here from typo tolerance

For details see:

MINOR Faceting on date fields

Date fields can now be used as facets, so users can filter results by dates such as when a product was created or last updated. Faceting is supported on both core date fields and custom (flow) date fields.

What's New?

  • Custom date field faceting - Date-typed custom fields are now facetable, joining the existing string, integer, float, and boolean facet types
  • Core date field faceting - Enable faceting on built-in date fields such as created_at and updated_at by setting facetable in core_field_overrides
  • Re-index required - A re-index is required for the change to take effect

For details see:

Upcoming deprecation of per_application promotion codes in Rule Promotions

MINOR Upcoming deprecation of per_application promotion codes in Rule Promotions

On September 14, 2026, we will remove the per_application value for the consume_unit field when creating promotion codes for Rule Promotions.

What's Changed?

  • consume_unit: per_application removed on September 14, 2026 - After this date, new promotion codes for a Rule Promotion can no longer be created with per_application; set consume_unit to per_checkout or omit the field to use the default
  • Existing codes are retained - Promotion codes already created with consume_unit: per_application continue to work as configured
  • Rule Promotions only - This change applies only to Rule Promotions. Promotion codes for standard (V1) Promotions are not affected

For details see:

Ask External AI