2024

New notifications endpoint, deprecated billing info validation rules, and more ⚠️

We've just added a new entry to the roster of our commerce API endpoints. You can leverage to attach specific messages or information to some resources. At the moment, notifications are available for orders and line items (in the future, the feature will be extended to other resources). On top of that, we released some minor updates to our APIs:

— we added the relationship with the payment source for all the transaction types (, , , and ).

— now you can filter orders also by payment source details. Furthermore, we you can now leverage the new trigger attribute _fix_payment_source to make order's payment source is correctly associated with the last succeeded authorization.

— we added the profile_id attribute, that you can leverage to uniquely identify the customer on any connected external services.

— we added the : symbol as an allowed character for tag names.

First open beta release for stores API

We've just released publicly our , a brand new endpoint that enables you to map a market's physical shops (e.g. retail stores, pop-up stores, etc.) to effectively manage in-store sales and more. Stores are market-specific and can have their own stock location and payment methods. Stores can be when requesting an access token so that all the fetched resources (e.g. SKUs, prices) are automatically filtered by the related market, orders are associated with the store in scope, the is computed taking into consideration the store's stock location (if any) first, and the are updated accordingly.

Check the and have a look at the data model for more information.

Bundles support for new orders, refund calculator, and more

Promotions — Now you can create directly from the Promotion App (closed beta feature, active for selected enterprise organizations only).

Now you can manually manage an edge case when an authorization or capture associated with an order that is still pending succeeds and the order is later updated (introducing an amount mismatch scenario). If so, you can leverage the new _cancel trigger attribute to and keep the order payment status unpaid. On top of that, in the past few days we released the following minor (but still relevant) updates to our APIs:

— now the payload also includes the shipments associated with the order together with the related shipping method.

— now you can leverage some additional predicates (e.g. *_eq_or_null, *_not_eq_or_null, *_in_or_null, or *_not_in_or_null) to include null values in the filter computation.

— now you can give the same name to SKUs identified by different SKU codes. We also expose the and relationships.

— now we also expose the and relationships.

— now also stock transfers support .

— we added the order number information to the usage log.

New Gift Cards app, details section, and more

As part of our new Dashboard renovations, we’ve released a new Gift Cards application to help you manage and complete the migration from the old Admin Area (that — let us remind you — will be sunset by the end of 2024). Now you can see all of your gift cards and filter them by market and status, create new gift cards, and edit, activate, and deactivate existing ones. Read more on our blog.

Monorepo management for all the apps, new Settings section, and more

We introduced two additional attributes you can set to manage when you're using order copies. Leveraging them you can decide to retrigger the promotions computation at the end of the copy and/or avoid copying to the target order any invalid coupon associated with the source order. On top of that, we released the following minor (but still relevant) updates to our APIs:

— now you're also allowed to cancel pending orders (not only placed or approved ones).

— now you can manage at the market level by defining the maximum of shipping line items of the order that will be charged.

— now you can also the line items options amount (you need to use API credentials).

— we added two new events to our so that you can get notified about failures and issues regarding tax calculation and external promotions.

We added the client ID of the application used to generate the for any kind of token issued by our . We also updated the issuer information. You can find an example of the updated token's payload structure .

are automatically triggered at creation time, notifying all listening webhooks. Now if you need to force the firing of an existing event manually, you can leverage the new _trigger attribute. This way, the event will be immediately triggered, regardless of its uniqueness. On top of that, we released the following minor (but still relevant) updates to our APIs:

— now, in case of , any active is automatically performed. We also relaxed the constraints on order fulfillment: now you can move an order fulfillment status to fulfilled as long as the associated shipments are cancelled, shipped, or delivered).

— now you can the associated item when exporting line items and the associated origin address, shipping address, and parcels when exporting shipments.

— now the name of the payment method is .

— now you can check the Adyen Checkout API version when fetching an Adyen gateway.

— we added reserved stocks to the list of resources.

Enabled full CRUD for carrier accounts API, and more

The endpoint isn't read-only anymore. Now you can , , and carrier accounts also via API (and not only using the admin UI). Remember that the credentials required to set up a carrier account depend on the specific shipping service you want to integrate. To check which credential keys are requested by each carrier you can fetch the carrier accounts schema from the core public endpoint /api/public/schemas/carrier_accounts. On top of that, we released an additional minor (but still relevant) update to our APIs:

— now you can also the reserved stock and the related stock location when exporting stock items.

We introduced the new _forward trigger attribute for all types of transactions (, , , and ). You can leverage it to unblock a transaction if it gets stuck (for any reason) on our platform but succeeds on the payment gateway. In the case of authorizations, the associated order is also placed at the end of the forwarding process, to avoid any possible modifications.

Added ability to initiate a refund from a return, and more

Now you can by sending two trigger attributes and specifying the amount to be refunded. By default, the capture that will be refunded is the most recently succeeded capture associated with the related order. In the case of an order associated with multiple captures, you can also specify a different capture, provided that it's succeeded as well. We also added the ability to directly mark requested and approved returns as received. On top of that, we released the following minor (but still relevant) updates to our APIs:

— now you can on which you want to apply an external promotion discount by listing their IDs in the line_items array of the response. You can also . The use of the matching_line_items key is deprecated. ⚠️

— now you can cancel also packing and ready-to-ship shipments by leveraging the new _cancel trigger attribute (you need to use API credentials).

— now you can cancel partially refunded orders without creating any further transactions.

— now we check and validate the related resources that are included in the request body so that you can be sure not to choose those that are not allowed. ⚠️

— we added order subscriptions to the list.

— we added order subscriptions to the list of resources we include in the we send to external payment gateways to avoid useless API roundtrips.

— we remove the uniqueness constraint on SKU names. Now you can give the same name to SKUs with different SKU codes.

Now you can decide to show the customer payment sources saved from the native Adyen Drop-in library instead of the ones by setting to true the new boolean attribute native_customer_payment_sources at the level (the feature is already available on our AdyenPayment React Component and will be soon added to our hosted Checkout too). On top of that, we released some other updates to our APIs:

— we exposed the new shopper_reference attribute. It is automatically generated at creation time for each new customer and sent to the payment gateway to identify the shopper during the payment sessions. It can be updated at your leisure.

— we update the list of relationships you can sort each resource by. You can find it in the documentation of each resource by checking the List all section (e.g. ).

— we removed the expires_at attribute, make sure to update your integration accordingly in case you were leveraging it somehow. ⚠️

— for performance reasons, now resource errors are limited to a buffer that stores the latest 10 errors per order. ⚠️

— now you can add to stock transfers too.

— we added the new delivered status to the shipment lifecycle. You can now leverage the related trigger attribute _deliver and . On top of that, now the number of a shipment can be .

— now you can leverage the new trigger attribute _fulfill to mark as fulfilled an order whose shipments have been shipped or delivered, and the related .

— now you can turn an existing order subscription into an one by sending the _covert trigger attribute, provided that you previously defined a subscription model for the associated market.

— now you are allowed to specify also some attributes that normally are not updatable (such as the order, payment, and fulfillment status) when that you want to archive.

— we exposed the new usage_log attribute that you can leverage to get more information about how, when, and by which order a gift card has been used.

— now the number of a stock transfer can be set at or time.

New price list scheduler endpoint, and more

We've just added a new entry to the roster of our commerce API endpoints that will enable better and more flexible pricing strategies and price list management. Now you can optionally associate one or more price list schedulers to each of your . set a time frame within which their overrides the associated market's one, letting you change a subset of prices within that specific time window (e.g. seasonal sales). On top of that, we added some minor updates to our APIs:

— now you can change a line item's unit amount and assign it a value that differs from the one defined in the market's price list of the associated order by using API credentials.

— we exposed the status of the promotion (e.g. expired, pending, active, inactive, or disabled) for all the promotion types.

Be advised that we introduced potential breaking changes ⚠️ by disabling on imports, meaning that the related events are no longer fired when creating/updating resources . The only events that are still fired are the ones associated with order status changes. If you need to leverage all the other real-time events, you have to create/update resources via the related API endpoints. On top of that, we added some minor updates to our APIs:

— now you can optionally define a custom alphanumeric code for your customer groups (similarly to what you could already do for , , and ).

— stock transfers are now both and .

— we added an upper limit to the subscription renewal alert period: now you can notify your customer of upcoming recurring orders from a minimum of one hour to a maximum of one month in advance. ⚠️

Updated UI design and new features for our Dashboard

We've released the newest version of our Dashboard, now built completely with React. It now leverages the power of our and APIs, making future development and customization of our Dashboard applications much easier. You'll notice a light UI revamp that improves the navigation, along with some new features. Among them:

Added the new Promotions, SKUs, SKU Lists, Price Lists, and Inventory apps to the dashboard hub

We doubled the number of allowed . Now you can define up to a maximum of 10 tiers in total (no matter what type) per .

We updated the list of our with a new event that you can leverage to about upcoming recurring orders associated with subscriptions once you've properly set the renewal_alert_period at the level. On top of that, we added some minor updates to our APIs:

— now all promotion types can be filtered by priority.

We introduced the new _validate trigger attribute at the level. We recommend passing it for each input when updating stock item quantities to avoid some edge-case scenarios that could lead to inconsistent quantity updates. On top of that, we added some minor updates to our APIs:

— we changed the SKU options' : now you can import SKU options using only name and currency code.

— Now you can returns even if the associated order's fulfillment status is unfulfilled.

Leveraging the recent new feature introduced on the Provisioning API in terms of adding default and market-specific settings at the level, we've started using those config parameters to enhance the flexibility of our hosted applications. The Checkout app now supports:

The tutorial on how to set up single-sign on with Commerce Layer using Next.js and Auth0 has been updated to reflect the changes recently introduced with our new . Read it on our blog and/or check the code in the Examples repository.

New Auth API supported from v6.0.0 ⚠️

The library now uses the and both the and authentication methods have been unified into the new authenticate one. ⚠️

The (including the additional feature to use the code instead of the ID) is now used.

We added order subscriptions to the list of . Now you can that include order subscription together with the associated order subscription items and customer payment source. On top of that, we also made the place_target_order option at the order subscription level.

Enabled full-text search on order's aggregated details

Now you can leverage a new attribute on the order field. aggregated_details contains all the order data, on which you can perform a using the dedicated query operator. On top of that:

We've added the archived_at to the order date_field available values and the archived attribute on the order field so that you can easily .

We've removed the 1-year limit on the within which you can request to extract your metrics.

Check the section of the Metrics API documentation for some examples and the public Postman collection to see it in action!

We've migrated the whole authentication process to our new , as detailed in the related section of the documentation. At the moment both the old and new ways of authenticating are supported, but the legacy endpoints, scope syntax, and SSO using a custom org-specific secret key are deprecated and will be dismissed by the end of October 2024. Make sure to in time to avoid any issues.

A new .

A new syntax for .

An additional authentication flow that enables token exchange in the (delegation) scenario.

The possibility to any kind of token.

To learn more, check the and read our blog here.

We’ve enabled the option to specify a basic configuration for Micro frontends and open-source apps (e.g. Cart, Checkout, Identity, My account, Microstore) at the organization level, via our . At the moment this feature is limited to the MFEs URL format and the Checkout app setup and will be progressively extended. You can specify the default values and possibly override them in a granular way (e.g. by market).

Added new subscriptions section in v1.4.1

Be advised that we introduced a potential breaking change ⚠️ by refining the check during the order placement. Altering those attributes during the order's placement process is not permitted, since they can trigger collateral effects and cause an inconsistent order status. Now, if try to edit them when you patch the order passing the _place trigger attribute no error is raised (to guarantee the order's placement), but the changes are silently ignored. On top of that, we added some minor updates to our APIs:

— we exposed a new virtual relationship on the that you can leverage to get all the line items included in the shipment (both the ones associated with stock line items and stock transfers).

— we added two new that you can leverage to when the last run of an order subscription has succeeded or failed.

Now all Commerce Layer are subject to a check. If the call to your external endpoint fails consecutively more than 30 times, the circuit breaker opens and any further request to the resource will be skipped. The circuit is automatically reset anytime a call to your external endpoint succeeds before reaching the counter's threshold. You can check the circuit breaker's current status by fetching some new specific attributes, and/or via trigger. On top of that, we added some minor updates to our APIs:

— now you can distribute the external promotion discount only on specific line items by adding their IDs to the sent by your external service.

— now you can promotions also by type.

— now you can customer payment sources also by payment source token.

— as recently done for gift cards, now you can leverage a specific attribute to prevent negative adjustment amounts from being distributed as discounts on all the taxable items of the order.

Now you can leverage a specific attribute at the single level to prevent the total discount due to gift cards used to pay for an order from being distributed on all the taxable items of the order. On top of that, we added some minor updates to our APIs:

— now the currency code is no longer required to create external promotions which can be applied across all currencies.

— now, when stock transfers become upcoming the related stock is no longer decremented. Instead, the necessary stock reservations are created to eventually allow order editing (the stock will be then actually decremented when the stock transfer is completed).

Asynchronous order placement and new resource errors endpoint

Now you can decide to place your orders by setting the related flag at the order level. In this scenario, if the order passes a subset of the synchronous standard validations it's momentarily moved to a new placing status where additional validations are performed (e.g. stock availability, coupons validity, etc.) before moving it through the next steps of its lifecycle. You can also check for errors that might keep an order stuck in placing by fetching the new endpoint, which will store until order approval not only any errors that occurred during the attempt to place an order (both synchronously and asynchronously), but also the ones coming from external validations, failed subscriptions, and more.

New split by line items inventory strategy

We added a new to the list of available ones. Now you can leverage the strategy by setting the related attribute accordingly at the inventory model level. This way, at least a separate shipment will be automatically created per each line item of the order. Please note that this new strategy only works for SKUS: if an order contains bundles, all the shipments and stock will be still managed by using the strategy as a fallback.

Now you can set an auto-place option at the to ensure your orders are automatically placed upon authorization performed asynchronously (at the moment, available for gateways only). On top of that, we added some minor updates to our APIs:

relationships — now, when creating a new promotion or updating an existing one, you can create or update the associated SKU list, but you can't create or update the associated coupons and promotion rules anymore.

— now you can manually create or update shipments even when the associated order is fulfilled.

— now you can create or update returns even when the associated order's fulfillment is in progress.

New Provisioning plugin

TypeScript SDK for Provisioning API

We’ve released our , which now enables Commerce Layer clients to manage provisioning tasks (such as organization creation, API credentials, memberships, roles and permissions management, etc.) programmatically instead of manually and exercise greater control over your organizational structure and user onboarding.

To learn more, check the and read our blog here.

Added the new Stock Transfers app to the dashboard hub

As part of our new Dashboard renovations, we’ve released a new Stock Transfers application to help you manage whenever your orders require one, allowing you to maintain a distributed inventory model without disrupting demand. You are now able to check all the key information behind each stock transfer and control their transition from one status to another. Click on the Hub tab and see it for yourself!

You can now leverage the feature — previously available via API only — also from the Orders app of the Dashboard, being able to edit orders (e.g. adding or removing items, coupons or gift cards, adjustments, etc.) after placement (and before approval).

Now you can override the default API behavior (automatic stock quantities decrementation and stock reservations cancellation at order approval) by setting a simple flag on the . That lets you manually manage those actions at any time after the order approval by leveraging the trigger attributes exposed at the and/or at the level.