For the complete documentation index, see llms.txt. This page is also available as Markdown.

2026

A year-to-date overview of Commerce Layer’s software updates, new features, and product improvements.

calendar-clock

Want a heads-up on upcoming breaking changes? Visit this page to see what's coming and update your integration in time. Looking for previous years? Browse the archive.

UpcomingArchive


Core API

Taxes reset upon address removal, and more

Removing both the shipping and billing addresses from an order with an associated tax calculator now resets all previously computed tax amounts to zero. On top of that, other smaller updates ship with this release:

  • Cleanups — if you want to evaluate filters and populate the records count without performing any deletion, you can now set the new dry_run attribute to true.

  • Checkout.com gateways — now expose an explicit trigger attribute that you can leverage to sync the gateway webhook endpoint with the Checkout.com workflow.

  • Vertex account — an account can now store an optional audience value, which is included in the login request only when set. Deployments that require it can configure it. Everyone else sees no change.

AICore APIMetrics API

Start building with AI

We've launched a dedicated documentation section covering everything you need to integrate AI agents and coding assistants with Commerce Layer. The foundation is a set of three purpose-built MCP servers, each targeting a specific kind of agent interaction:

  • Core MCP — The primary integration for agents that need to read and write commerce data. Covers operational queries, schema discovery, and order workflows.

  • Metrics MCP — Gives agents access to order, cart, and returns analytics, backed by the Metrics API.

  • Documentation MCP — Surfaces real-time access to the full developer docs, built for coding assistants and IDE integrations.

Meet the Commerce Layer Core MCP.

Discover how the Commerce Layer Core MCP server gives AI agents secure, schema-aware access to commerce operations. Learn how discovery, validation, and documentation-aware workflows enable agents to work safely across the entire platform.

Read more on our blog Contact sales

Core APIStream hub

Data retention policy for event stores

We've defined a clear data retention policy for event stores — which will consequently affect the replay stream of the event stream hub — with different retention windows depending on the type of resource, its mode, and the event type involved. Check the docs for the full details — including specifics on deleted resources, test mode data, and which event types are stored for each resource.

Core APIBreaking

Document-level meta fields in API responses

API responses now include mode, organization_id, and trace_id at the document level, inside a root meta object (alongside the pagination fields already present in list responses) — in addition to the existing resource-level meta information.

Deprecation — September 15, 2026

Core APIBreaking

Case-sensitive and case-insensitive filter predicates

Filter predicates belonging to the _cont family are now case-sensitive. If you need case-insensitive matching, make sure to update your integration to use the newly introduced _i_cont, _i_cont_any, _i_cont_all, _not_i_cont_any, and _not_i_cont_all counterparts.

Dashboard

Resource inspector in Orders and Promotions apps

A new inspect button is now available on order and promotion detail pages. It opens a panel showing the full resource details — attributes and a chronological event log covering status changes, attribute updates, and who triggered each action (user, worker, or application).

user-lock

Available for Enterprise customers as part of the Event stream hub.

Dashboard

Configurable return reasons and shipping method duplication

Two small but handy Dashboard enhancements ship with this release:

  • You can now define a list of predefined return reasons at the organization level, directly from the Shipping section in Settings. Once configured, these reasons are surfaced as suggestions when a return is requested — while still allowing customers to enter a custom reason if needed.

  • Shipping methods now support duplication — useful, for example, when you need to create a variation of an existing method with just one setting changed, without having to recreate the whole configuration from scratch.

Core APIBreaking

Versions endpoint removed, and more

The versions endpoint and all the corresponding relationships across previously versionable resources have been permanently removed. This resource has been deprecated since August 2025, when version storage was discontinued.

signal-stream

On top of that, two smaller updates ship with this release:

  • All payment gateways now expose a credential_keys attribute, returning the last digits of each configured API credential key. Gateways that provide an official client — Adyen, Braintree, Checkout.com, PayPal, and Stripe — also expose a new _check trigger attribute to validate credentials against the gateway's API directly.

  • All timestamp attributes across resources have been updated from type datetime to type string (with datetime format), aligning with JSON Schema conventions.

Core APIDashboard

Anomaly detection and alerting, now available

We're introducing anomaly detection as a new capability inside Commerce Layer. The system continuously monitors your order workflows in real time, automatically identifying deviations from expected behavior — such as discrepancies between order placement and approval, or unusual shifts in payment method distribution. Instead of relying on static thresholds, it learns what "normal" looks like over time and triggers immediate alerts when something is off, so your team can investigate and act before issues impact customers or revenue.

user-lock
From anomalies to action: stopping issues before they escalate.

Catch what’s off before it becomes a problem. Real-time anomaly detection helps you monitor workflows, identify deviations early, and take action in time.

Read more on our blog Contact sales

DashboardMetrics API

Meet the new Metrics dashboard

The Metrics dashboard is now live — a single place inside Commerce Layer where commerce teams can monitor performance, explore trends, and go from insight to action without jumping across tools.

All metrics are updated in real time and the dashboard launches with four key sections: Orders, Promotions, Returns, and Carts. Every element is fully interactive, with flexible time range comparisons, powerful filtering by dimensions like market, currency, country, and tags, and one-click drill-downs into the underlying orders.

user-lock
Introducing the Metrics Dashboard.

Get a clear, actionable, real-time view of your commerce performance. Explore trends, compare results, and understand what’s driving your business — all in one place.

Read more on our blog Contact sales

rocket-launch
Metrics API

New queryable fields for returns

The returns resource in the Metrics API now exposes two new fields — return_line_items.name and return.currency_code — available across all query types (breakdown, date breakdown, stats, search, and export). This makes it possible to group and analyze return data by product name or currency, enabling insights like which products are returned most frequently, return quantities per product, and multi-currency return aggregations.

Core API

Removed export size limit

Exports just got a significant upgrade. There is now no limit on export size — large jobs are processed in multiple rounds, prioritizing reliability, with new attributes available to monitor how things are going (number of processed exports, estimated completion time, etc.). On top of that, you can now interrupt a running export at any time and restart it from where it left off, making it much easier to manage long-running jobs.

Core API

Coupons count info for promotions, and more

Now you can check the total number of coupons created for a specific promotion by inspecting the related attribute on the single promotion type. On top of that, in the past few days, we released the following minor (but still relevant) updates:

  • Transactions — now you can get information about the payment method used in a transaction (available for all transaction types).

  • Shipping methods — now you can add and remove tags to shipping methods like any other taggable resource.

  • Bundles — now you can sort bundles by name as well.

Metrics API

New export query

The Metrics API now supports a new query type. The export query is a CSV-flavored variant of the search query that returns matching records as a plain text/csv file, sorted and filtered to your needs. Available for orders, returns, and carts, with up to 100K records per export.

Rules Engine

New free gift action and date-based dynamic values

We just shipped two new Rules Engine capabilities that expand what you can express in your rules — one on the actions side, one on the conditions side:

  • Free gift action — A new free gift action type is now available for flex promotions. It applies a 100% discount to specific line items added to the cart as free gifts, with full control over which items are eligible and how many units are discounted. Remember that Commerce Layer also exposes two dedicated order relationships that targets the available free SKUs and bundles to make it easy to surface a gift selection UI at checkout.

  • Date-based dynamic values — Condition values now support date expressions, making it straightforward to write time-sensitive rules without hard-coding any dates. You can reference the current date, extract date parts, match birthdays, or define date windows — all using the same notation already available for dynamic values (see some example and real use cases on our latest blog post).

Birthday coupons and spend limits with Commerce Layer.

Learn how to use Commerce Layer’s Rules Engine to create birthday discounts, limit eligibility with customer metadata, and manage dynamic spend thresholds with precision.

Read more on our blog Contact sales

Core API

Option to disable payment gateways, and more

We just powered the whole set of our supported payment gateways with a couple of new options:

  • Disable / enable — Now you can disable the payment gateways you don't use anymore (and possibly re-enable them, if needed) by passing a new trigger attribute on the specific payment gateway type. Active / inactive payment gateways can be retrieved by filtering / sorting the list by the new disabled_at timestamp with the proper query.

  • Force payments — the force payments option is now available on additional payment gateways beyond Stripe (for which it was already enabled by default). For those gateways (including Adyen, Axerve, Checkout.com, Satispay, and all external gateways), the feature is not enabled, meaning that the value for the force_payments option is false. Set it to true on the specific gateway if you want incoming payment events to automatically align the order’s payment source with the one used by the transaction (as long as the order is still editable).

Core API

Custom include list for external resources, and more

Now you can overwrite the default list of resources included in the request payload of all the external resources (external order validations excluded) and specify a custom one. The allowed includes are based on the target resource required by the external request. Providing an invalid include for the target resource will result in an error. On top of that, in the past few days, we released the following minor (but still relevant) updates: