Skip to main content

Managing inventory sync with the Event stream

This guide focuses on integration using the Event Stream , this is the recommended way. The older alternative is available at Managing inventory sync .


If you work with an ERP that manages fulfillment and no other applications in your project need fulfillment-related data, you do not need this guide. Instead, refer to Integrating a fulfillment provider and Importing data .

Syncing inventory is a continual 2-way process that involves:

How inventory sync works

To sync inventory changes from your business into NewStore Omnichannel Cloud, develop an adapter. An adapter serves as an intermediary integration layer that communicates directly with NewStore Omnichannel Cloud on one side and with business applications that you want to integrate NewStore with, on the other.

Let's assume your product stock is 10. If 4 items of this product were shipped as part of different orders, here's how inventory will be synced.

The workflow is as follows:

  1. NewStore sends fulfillment data items to an adapter via fulfillment request events with logical timestamps to identify the items that failed, were assigned or were completed.
  2. The adapter syncs inventory changes and remove allocations in your business.
  3. On NewStore side, when you import stock into NewStore, include a range of logical timestamps for which to remove allocations.

When an item is shipped, the fulfillment_request.items_completed event is emitted.

Each fulfillment event in NewStore is for one item and it is associated with a logical timestamp. A logical timestamp is a number that consistently increases and helps arrange fulfillment events in the sequence in which they occurred. If fulfillment events ff1, ff2, ff3, and ff4 are assigned logical timestamps 10, 11, 12, 13 respectively where 13 is the highest, ff4 is the most recently fulfilled item.

When an item is shipped, allocation for the associated item is removed from NewStore Omnichannel Cloud.

Syncing inventory

Here's a quick overview of the methods to implement and sync inventory between NewStore Omnichannel Cloud and other applications:

sequenceDiagram participant N as NewStore participant A as Adapter participant E as Other applications N->>A: /event (POST) [fulfillment_request.items_completed] Note over N,A: Initial stock for the product was 10, and ff1, ff2, ff3 were completed with logical timestamps 10, 11, 12. A->>E: Stock changes Note right of E: Stock is updated to 7 and 3 allocations are removed. A->>N: /import (POST) activate A E->>A: Stock changes Note over E,A: Stock is imported with current on hand value set to 17, and includes a logical timestamp range 10-12 to identify allocations to be removed. See "Usage guidelines". A->>N: /import/import_id/start (POST) deactivate A Note left of N: Stock is updated to 17 and allocations are removed for items in ff1, ff2, ff3.

Syncing inventory to other applications

Once you implement the Publish event method, the webhook sends you data about several events. In the context of fulfillment, the following events are emitted:

  • fulfillment_request.assigned: allows you to initially retrieve the fulfillment id.
  • fulfillment_request.items_completed: tells you which items have been fulfilled. If needed, you can use this event to ensure that the ERP releases the allocations for the fulfilled items.
  • fulfillment_request.items_failed: tells you which items failed to be fulfilled. The allocations for these items are released for that location and the request is automatically routed to another fulfillment location. If no location can fulfill, the order is put on hold.

See the Event stream webhooks documentation for a description of the content of the event.


You should use the fulfillment_request.items_completed event instead of the order.completed event:

  • order.completed doesn't include where the item was shipped from.
  • order.completed doesn't include the logical timestamp which controls the allocation release on ATP import.

Syncing inventory to NewStore Omnichannel Cloud

Use the import job to sync inventory into NewStore Omnichannel Cloud. Use the prescribed JSON schema for stock. As soon as items are shipped, allocations for the items are removed from NewStore Omnichannel Cloud.

Inventory in NewStore Omnichannel Cloud and in your business are now in sync.

Related topics