Merchant API: stock locations

About this article

This article explains how to set up and use stock locations via the ChannelEngine Merchant API. Learn how to create locations with POST /v2/stocklocations, retrieve them with GET /v2/stocklocations, and reference them in stock updates and shipment calls.

Table of contents

Introduction

Overview

Why use stock locations

Requirements

Available API endpoints

• GET /v2/stocklocations
• POST /v2/stocklocations

Using stock locations

• Reporting stock per location
• Updating stock per location
• Fulfilling orders from a specific location
• Order routing and multi-warehouse marketplaces
• Stock limits

Common issues

Next steps

Introduction

If you keep stock in more than one place – your own warehouse, a 3PL, or a marketplace's fulfillment network like FBA, LVB, or ZFS – you can benefit from ChannelEngine's advanced order management feature.

With advanced order management, you can configure stock in multiple locations and allocate your stock accordingly. This feature allows you to set up rules to define the default behavior when stock is depleted in one of your locations, and automatically allocate inventory from a specific location to fulfill your orders.

The core loop is straightforward: create a stock location, report and update stock per location, then reference that location when fulfilling orders. Every stock update and shipment call should be tied to the exact place the product came from.

Overview

Refer to the flowchart below to visualize how stock locations are created, retrieved, and referenced across stock updates and order fulfilment on ChannelEngine.

Each stock location is assigned a ChannelEngine Id, a Name, and a CountryIso (e.g.: NL, BE, or FR). Retrieve the full list with GET /v2/stocklocations and create new ones with POST /v2/stocklocations.

Why use stock locations

Setting up stock locations pays off as soon as you're managing inventory in more than one place:

• Accurate stock, per warehouse. Instead of one combined number, you get a true picture of how much is available at each location, useful if locations serve different regions or channels.
• Combine your own stock with marketplace fulfilment. Stock held at a marketplace's own fulfilment center (FBA, LVB, ZFS, etc.) is represented as a stock location too, so you can see it alongside your own warehouses in one place.
• Smarter fallback behavior. With FallBackToDefault, you decide whether a channel should only use its dedicated fulfilment location, or fall back to merchant fulfilment when that location runs out of stock.
• Clearer order fulfilment. When you ship an order, you can tell ChannelEngine exactly which stock location the package came from, useful for reporting and multi-warehouse operations.
• Foundation for channel-level stock rules. Stock location IDs are the building block for more advanced setups, like product-level stock limitations per channel. See ChannelEngine: stock.
• Support for virtual stock locations. A stock location does not have to be a physical address – you can create a virtual stock location to represent a logical split of stock (e.g.: stock reserved for a specific channel) without it corresponding to an actual warehouse.
• Required for order routing. ChannelEngine's order routing feature decides which warehouse should fulfill an order based on your stock locations.
• Needed for multi-warehouse marketplaces. Some marketplaces support multi-warehousing themselves, which means the marketplace needs to know which of its own warehouses an order should route to. That only works if there's a 1-to-1 mapping between your ChannelEngine stock location and the corresponding warehouse set up on the marketplace side.

Requirements

Before you start, make sure you have:

• Access to the ChannelEngine Merchant API with valid credentials.
• A clear picture of every place you hold stock – your own warehouses, any 3PLs you use, and any virtual locations you want to represent. You do not need to prepare anything for marketplace fulfilment programmes (FBA, LVB, ZFS, etc.), since ChannelEngine creates those locations for you.
• The country and address details for each physical location you want to add.

Available API endpoints

The following endpoints let you create and retrieve stock locations, report and update stock per location, and link fulfilment actions to a specific warehouse.

• Create a stock location: POST /v2/stocklocations
  Creates a new stock location for a warehouse, 3PL, or virtual location that you manage. Do not use this endpoint for marketplace fulfilment locations – ChannelEngine adds those automatically.
• Retrieve all stock locations: GET /v2/stocklocations
  Returns every stock location currently set up for your account, including its Id, Name, and CountryIso. The response may include marketplace fulfilment locations (FBA, LVB, ZFS, etc.) that ChannelEngine created automatically.
• Retrieve stock per location: GET /v2/offer/stock
  Returns current stock quantities across your warehouses. Pass one or more StockLocationIds to filter results down to specific locations, or omit the parameter to retrieve stock across all of them.
• Update stock per location: PUT /v2/offer/stock
  Updates stock per product. Each product update includes a StockLocations array where every entry has a Stock quantity and an optional StockLocationId.
• Retrieve fulfilment stock: GET /v2/fulfillmentstock
  Returns a view of product stock across all warehouses set up as stock locations for channel fulfilment.

Create stock locations

Use POST /v2/stocklocations to create a stock location on ChannelEngine. Use this only for locations you manage yourself – your own warehouse(s), a 3PL, or a virtual stock location. Do not use it to create marketplace fulfilment locations; ChannelEngine adds those automatically.

Request body

Example: creating a warehouse in the Netherlands and setting it as the default stock location

POST https://{your-subdomain}.channelengine.net/api/v2/stocklocations

{
  "Name": "Warehouse NL - Rotterdam",
  "IsDefault": true,
  "FallBackToDefault": true,
  "Address": {
    "CountryIso": "NL",
    "StreetName": "Waalhaven Zuidzijde",
    "HouseNr": "18",
    "HouseNrAddition": null,
    "ZipCode": "3087 BM",
    "City": "Rotterdam",
    "Region": null
  },
  "PhoneNumber": "+31101234567"
}

Example: creating a minimal virtual stock location (only Name and Address.CountryIso are required)

{
  "Name": "Reserved stock, Bol.com",
  "Address": {
    "CountryIso": "NL"
  }
}

Responses

Retrieve stock locations

Call GET /v2/stocklocations to retrieve every stock location currently in use for your account, including its Id, Name, and CountryIso.

Using stock locations

Report stock per location

Call GET /v2/offer/stock to return the stock available across your warehouses. Pass one or more StockLocationIds to filter results down to specific locations, or leave the parameter out to see stock across all of them.

Alternatively, call GET /v2/fulfillmentstock to view product stock across all warehouses set up as stock locations for channel fulfilment.

Update stock per location

Call PUT /v2/offer/stock to update stock per product. Each product update includes a StockLocations array, where every entry has a Stock quantity and an optional StockLocationId.

Fulfill orders from a specific location

When you pull orders, each order line includes a StockLocation object with the location's Id and Name – the same Id returned by GET /v2/stocklocations. Use it to identify which of your stock locations should pick and fulfill that order line.

When you mark an order as shipped, include the stock location ID via ShippedFromStockLocationId so ChannelEngine – and the marketplace, where supported – knows exactly which warehouse the package came from. This matters whenever you fulfill orders from more than one location.

Order routing and multi-warehouse marketplaces

ChannelEngine's order routing feature decides which warehouse should fulfill each order. For most marketplaces, that decision only needs to make sense on your side. So you set up predefined business rules that assign incoming orders to specific stock locations.

However, a number of marketplaces support multi-warehousing themselves, meaning the marketplace also knows about your individual warehouses, and an order needs to be routed to the correct one on the marketplace's side, too.

For these marketplaces, each of your ChannelEngine stock locations must map 1-to-1 to the matching warehouse configured on the marketplace. If a ChannelEngine stock location does not have a corresponding warehouse on the marketplace side (or vice versa), order routing can send an order to the wrong warehouse, or fail to route it at all. Use the stock settings to import the channel's warehouses and map them to your stock locations, then verify your setup with your ChannelEngine contact before going live.

Stock limits

Stock location IDs also feed into stock limits you set on the product level per channel, i.e.: when sending a request to the POST /v2/offer/{channelId}product-level-stock-limitations endpoint. If you define a stock limit at the channel level and leave out the stock location of that request, any stock settings (Stock buffer and Stock limit) that you configured in the web interface take priority. See ChannelEngine: channel stock settings.

Common issues

Testing flow

Use the testing flow below to confirm your stock location setup works correctly before going live.

Test 1: create and retrieve a stock location

1. Call POST /v2/stocklocations with a test Name and an Address containing at least CountryIso.
   Expected result: HTTP 201 Created.
2. Call GET /v2/stocklocations and find your new location in the list.
   Expected result: the response includes your location's Id, Name, and CountryIso.
3. Open the Stock locations page in your ChannelEngine tenant at https://[your-tenant].channelengine.net/stocklocations.
   Expected result: your new stock location is visible in the list.

Test 2: update stock for a specific stock location

1. Call PUT /v2/offer/stock for a test product, with a StockLocations entry referencing the StockLocationId from Test 1.
   Expected result: HTTP 200, updates processed without warnings.
2. Call GET /v2/offer/stock filtered by that StockLocationId for the same product SKU.
   Expected result: the returned Stock quantity matches what you sent.
3. Open the same product in the product detail page on ChannelEngine.
   Expected result: the product's stock is shown split out per stock location, and the quantity for your test location matches what you sent via the Merchant API.

Test 3: filter stock by location

1. Call GET /v2/offer/stock without any StockLocationIds filter.
   Expected result: stock across all your locations is returned.
2. Repeat the call with StockLocationIds set to only your test location's ID.
   Expected result: the result is narrowed down to that single location.

Next steps

• Once your stock locations are set up, review product-level stock limitations per channel to control how stock is allocated when a channel-level limit is not in place.
• Include the StockLocationId on every stock update if you operate from more than one location, rather than relying on the default location.
• When shipping orders, always set ShippedFromStockLocationId if you fulfill from multiple warehouses.
• Check that you do not run into the rate limits.