Merchant API: offers

About this article

This article explains how to manage offer data — stock and price — via the Merchant API, including how to submit offers with or without stock locations, how to retrieve current stock levels, and how to configure stock buffer and limit settings per channel.

Table of contents

About this article

Introduction

Overview

Requirements

Available API endpoints

Key concepts

• What is an offer?
• What is a stock location?
• Choosing between endpoints

Submitting an offer without stock locations

Submitting offers with multiple stock locations

Updating stock and price together

Retrieving stock from ChannelEngine

Stock buffer and stock limit

Common issues

Onboarding test script

• Test 1 — Submit a basic offer
• Test 2 — Create stock locations
• Test 3 — Retrieve stock location IDs
• Test 4 — Submit stock per location
• Sign-off checklist

Next steps

Introduction

Getting your products live on marketplaces requires two things: product content (name, description, images) and offer data (stock and price). While product content is submitted via the Products endpoints, stock and price are always managed through the Offers endpoints. This separation means you can update commercial data independently from content — and as frequently as your business requires.

This article covers two scenarios: submitting offers when you operate a single warehouse (no stock locations), and submitting offers across multiple warehouses using ChannelEngine's stock location feature.

Overview

Refer to the flowchart below to visualize how offer data travels between your system, ChannelEngine, and connected channels.

Requirements

To use the offers endpoints, you need the following:

• A valid Merchant API key, passed in every request as the X-CE-KEY header.
• Products already created in ChannelEngine via POST /v2/products — offer data can only be submitted for existing products.
• If you use multiple warehouses: stock locations must be created via POST /v2/stocklocations before submitting per-location stock.

Available API endpoints

The following endpoints are covered in this article. All endpoints are prefixed with https://api.channelengine.net/api.

• Update stock and/or price: PUT /v2/offer
  Update stock, price, or both for one or more products in a single call. Applies to the default stock location unless a StockLocationId is specified.
• Update stock per stock location: PUT /v2/offer/stock
  Update stock across multiple stock locations for one or more products. Each product entry accepts a StockLocations array. Does not update price.
• Retrieve submitted stock levels: GET /v2/offer/stock
  Retrieve the stock values you have submitted to ChannelEngine, per product and per stock location.
• Retrieve marketplace fulfillment stock: GET /v2/fulfillmentstock
  Retrieve stock levels held at marketplace fulfillment warehouses (e.g.: Amazon FBA, Zalando ZFS), including a granular breakdown by quantity type.
• Create a stock location: POST /v2/stocklocations
  Register a warehouse, 3PL site, or virtual stock location in ChannelEngine. Required before submitting per-location stock.
• Retrieve stock locations: GET /v2/stocklocations
  Retrieve all stock locations and the IDs assigned to each one, including any marketplace fulfillment locations created automatically by ChannelEngine.
• Retrieve stock buffer and limit settings: GET /v2/offer/{channelId}/product-level-stock-limitations
  Retrieve the current stock buffer and limit settings configured for a specific channel.
• Set stock buffer and limit settings: POST /v2/offer/{channelId}/product-level-stock-limitations
  Create or update stock buffer or limit settings for one or more products on a channel.
• Remove stock buffer and limit settings: DELETE /v2/offer/{channelId}/product-level-stock-limitations
  Remove stock buffer or limit settings for specific products and stock locations on a channel.

Key concepts

Before submitting offers, it helps to understand how ChannelEngine handles stock and price data.

What is an offer?

An offer is the commercial representation of a product — its price and available stock. Offer data is separate from product content and is always submitted through the Offers endpoints, never through the Products endpoints.

What is a stock location?

A stock location is any logical unit of storage you want to track stock for separately in ChannelEngine. This does not have to be a physically different building or warehouse — a stock location can also represent a virtual shelf, a zone in your warehouse management system (WMS), a consignment area, or a bonded section of a single warehouse. If your WMS tracks stock in separate buckets (for example, "available", "quarantine", or "reserved"), each bucket can be modelled as its own stock location in ChannelEngine.

If you ship from a single pool of stock with no logical separation, you can submit offers without specifying a stock location at all — ChannelEngine applies it to the default location automatically.

Choosing between endpoints

Use the table below to identify which endpoint fits your scenario.

Submitting an offer without stock locations

If you operate a single warehouse, use PUT /v2/offer to update stock and price for one or more products. No stock location setup is required — ChannelEngine applies the values to your default stock location automatically.

You can update stock and price together in a single call, or independently. Send only the fields that have changed — if you send Stock without Price, the price remains unchanged, and vice versa.

Request body fields

Example requests

Update stock and price for a single product:

// PUT /v2/offer — update stock and price
[
  {
    "MerchantProductNo": "SKU-001",
    "Stock": 42,
    "Price": 79.99
  }
]

Update stock only for multiple products:

// PUT /v2/offer — stock update only, bulk
[
  {
    "MerchantProductNo": "SKU-001",
    "Stock": 42
  },
  {
    "MerchantProductNo": "SKU-002",
    "Stock": 0
  },
  {
    "MerchantProductNo": "SKU-003",
    "Stock": 130
  }
]

Update price only for a single product:

// PUT /v2/offer — price update only
[
  {
    "MerchantProductNo": "SKU-001",
    "Price": 74.99
  }
]

Submitting offers with multiple stock locations

If you ship from multiple warehouses, ChannelEngine can track stock per location and aggregate the totals per channel. To set this up, you first create each warehouse as a stock location in ChannelEngine, then submit stock using the stock location IDs.

The setup follows three steps:

1. Create each warehouse as a stock location — POST /v2/stocklocations
2. Retrieve the IDs assigned to each location — GET /v2/stocklocations
3. Submit stock per location using those IDs — PUT /v2/offer/stock

Step 1 — Create a stock location

Use POST /v2/stocklocations to register each stock location in ChannelEngine — whether it is a physical warehouse, a 3PL site, or a virtual shelf in your WMS. You only need to do this once per location. After creation, use the assigned ID for all future stock updates.

Example request — create a warehouse:

// POST /v2/stocklocations
{
  "Name": "Warehouse NL",
  "IsDefault": true,
  "PhoneNumber": "+31201234567",
  "Address": {
    "CountryIso": "NL",
    "StreetName": "Keizersgracht",
    "ZipCode": "1015 CJ",
    "HouseNr": "424",
    "City": "Amsterdam"
  }
}

Step 2 — Retrieve the stock location ID

After creating your stock locations, call GET /v2/stocklocations to retrieve the IDs that ChannelEngine has assigned to each one. These IDs are required when submitting stock per location in step 3.

// GET /v2/stocklocations — example response
{
  "Content": [
    {
      "Id": 12,
      "Name": "Warehouse NL",
      "CountryIso": "NL"
    },
    {
      "Id": 15,
      "Name": "3PL Germany",
      "CountryIso": "DE"
    },
    {
      "Id": 21,
      "Name": "Amazon FBA EU",
      "CountryIso": "DE"
    }
  ],
  "Count": 3,
  "TotalCount": 3,
  "Success": true
}

Step 3 — Submit the offer per stock location

Use PUT /v2/offer/stock to submit stock for one or more products across multiple locations. Each product entry contains a StockLocations array — one entry per warehouse. You can update all locations for a product in a single call.

Update stock for a single product across two locations:

// PUT /v2/offer/stock — submit stock per location
[
  {
    "MerchantProductNo": "SKU-001",
    "StockLocations": [
      {
        "StockLocationId": 12,
        "Stock": 80
      },
      {
        "StockLocationId": 15,
        "Stock": 35
      }
    ]
  }
]

Update stock for multiple products across multiple locations in one call:

// PUT /v2/offer/stock — bulk multi-location stock update
[
  {
    "MerchantProductNo": "SKU-001",
    "StockLocations": [
      { "StockLocationId": 12, "Stock": 80 },
      { "StockLocationId": 15, "Stock": 35 }
    ]
  },
  {
    "MerchantProductNo": "SKU-002",
    "StockLocations": [
      { "StockLocationId": 12, "Stock": 20 },
      { "StockLocationId": 15, "Stock": 0 }
    ]
  }
]

Updating stock and price together

PUT /v2/offer is the endpoint for updating both stock and price in a single call. It supports stock locations too — by including StockLocationId in the request, you can target a specific location while also setting a price. This makes it the most flexible offer endpoint: it covers single-warehouse sellers, multi-location sellers, and any combination of stock-only or price-only updates.

Update stock at a specific location and price in one call:

// PUT /v2/offer — update stock at location 15 and set a new price
[
  {
    "MerchantProductNo": "SKU-001",
    "Stock": 60,
    "Price": 74.99,
    "StockLocationId": 15
  }
]

Update stock at multiple locations and price for multiple products in one call:

// PUT /v2/offer — mixed bulk: different locations per product, plus price
[
  {
    "MerchantProductNo": "SKU-001",
    "Stock": 80,
    "Price": 74.99,
    "StockLocationId": 12
  },
  {
    "MerchantProductNo": "SKU-001",
    "Stock": 35,
    "StockLocationId": 15
  },
  {
    "MerchantProductNo": "SKU-002",
    "Stock": 20,
    "Price": 39.99,
    "StockLocationId": 12
  }
]

Retrieving stock from ChannelEngine

ChannelEngine provides two endpoints for reading stock data, depending on whether you want to check your own submitted stock levels or the stock held at a marketplace fulfillment warehouse.

GET /v2/offer/stock — your submitted stock levels

Use GET /v2/offer/stock to verify the stock values you have submitted to ChannelEngine — per product and per stock location. The response shows the stock value stored at each location along with the timestamp of the last update.

Query parameters

Response fields

// GET /v2/offer/stock?Skus=SKU-001,SKU-002&StockLocationIds=12,15
// Example response
{
  "Content": [
    {
      "MerchantProductNo": "SKU-001",
      "StockLocationId": 12,
      "Stock": 80,
      "UpdatedAt": "2026-08-07T09:14:00Z"
    },
    {
      "MerchantProductNo": "SKU-001",
      "StockLocationId": 15,
      "Stock": 35,
      "UpdatedAt": "2026-08-07T09:14:00Z"
    }
  ],
  "Success": true
}

GET /v2/fulfillmentstock — marketplace fulfillment warehouse stock

When you activate a Fulfillment by Channel programme — such as Amazon FBA or Zalando ZFS — ChannelEngine automatically creates a dedicated stock location for that marketplace warehouse. ChannelEngine then imports the stock levels from the marketplace's warehouse directly into this location. Use GET /v2/fulfillmentstock to read these imported stock levels, broken down into granular quantity types such as available, reserved, in transit, damaged, and more.

To find the stock location ID for a marketplace warehouse, call GET /v2/stocklocations and look for locations with names matching the marketplace (e.g.: "Amazon FBA EU"). The Id returned is what you pass to filter this endpoint.

Query parameters

Response fields — stock quantity breakdown

Unlike GET /v2/offer/stock, the fulfillment stock response returns a StockLocations array per product — one entry per marketplace warehouse — each containing a granular breakdown of how that stock is classified at the fulfillment centre.

// GET /v2/fulfillmentstock?MerchantProductNos=SKU-001
// Example response — FBA stock breakdown for SKU-001
{
  "Content": [
    {
      "MerchantProductNo": "SKU-001",
      "StockLocations": [
        {
          "Id": 21,
          "Name": "Amazon FBA EU",
          "AvailableQuantity": 340,
          "ReservedQuantity": 12,
          "InTransitQuantity": 200,
          "InboundQuantity": 200,
          "FulfillmentCenterProcessingQuantity": 8,
          "DefectiveQuantity": 2,
          "ExpiredQuantity": 0,
          "WarehouseDamagedQuantity": 1,
          "CustomerDamagedQuantity": 3,
          "CarrierDamagedQuantity": 0,
          "ReturnQuantity": 5,
          "ResearchingQuantity": 0,
          "UpdatedAt": "2026-08-07T06:30:00Z"
        }
      ]
    }
  ],
  "Success": true
}

Replenishment workflow example

A common use case is to build a replenishment alert or automated trigger based on fulfillment stock data. The recommended approach is:

1. Find the stock location ID for the marketplace warehouse by calling GET /v2/stocklocations and identifying the entry for your fulfillment programme (e.g.: "Amazon FBA EU"). Note its Id.
2. Call GET /v2/fulfillmentstock on a schedule (daily or more frequently). Filter by the SKUs you want to monitor.
3. Read AvailableQuantity for the relevant stock location ID in each product's StockLocations array. This is the sellable stock the marketplace currently holds for you.
4. Compare against your reorder threshold. If AvailableQuantity plus InTransitQuantity (stock already on its way) falls below your threshold, flag the product for replenishment and initiate a new inbound shipment to the marketplace warehouse.

Stock buffer and stock limit

ChannelEngine lets you apply two types of stock controls at the product level per channel: a stock buffer and a stock limit. Both affect how much stock ChannelEngine exports to a channel — without changing the actual stock value in your system. These settings are channel-specific and product-level — they apply to a specific channel and can vary per stock location within that channel. They do not affect your actual stock values or what other channels see.

Stock buffer

A fixed number of units to subtract from the exported stock. ChannelEngine deducts the buffer from your available stock before sending it to the channel. For example: you have 50 units in stock and a buffer of 10 — the channel sees 40 units. Use this to protect against overselling by keeping a safety reserve that channels cannot deplete.

Stock limit

A maximum number of units that can ever be exported to a channel, regardless of how much stock you actually have. For example: you have 500 units in stock and a limit of 20 — the channel sees 20 units at most. Use this to control how much exposure a channel gets — for example, capping a new marketplace while you test performance.

Setting a stock buffer or limit

Use POST /v2/offer/{channelId}/product-level-stock-limitations to create or update settings. The body accepts an array of products, each with one or more stock location entries.

Set a stock buffer of 5 units for two products on a channel:

// POST /v2/offer/42/product-level-stock-limitations
// Channel ID 42, default stock location, buffer of 5 units
{
  "ProductsStockLimitations": [
    {
      "MerchantProductNo": "SKU-001",
      "ProductLocationsStockLimitations": [
        {
          "StockBuffer": 5,
          "StockLimit": null
        }
      ]
    },
    {
      "MerchantProductNo": "SKU-002",
      "ProductLocationsStockLimitations": [
        {
          "StockBuffer": 5,
          "StockLimit": null
        }
      ]
    }
  ]
}

Set a stock limit per stock location for one product:

// POST /v2/offer/42/product-level-stock-limitations
// Limit of 20 units at location 12, limit of 10 at location 15
{
  "ProductsStockLimitations": [
    {
      "MerchantProductNo": "SKU-001",
      "ProductLocationsStockLimitations": [
        {
          "StockBuffer": null,
          "StockLimit": 20,
          "StockLocationId": 12
        },
        {
          "StockBuffer": null,
          "StockLimit": 10,
          "StockLocationId": 15
        }
      ]
    }
  ]
}

Retrieving current settings

Use GET /v2/offer/{channelId}/product-level-stock-limitations to see what buffer and limit settings are currently active for a channel. Use the Page query parameter to paginate through results. Each product in the response contains a ProductLocationsLimitations array showing the StockBuffer and StockLimit per stock location.

// GET /v2/offer/42/product-level-stock-limitations — example response
{
  "Content": [
    {
      "MerchantProductNo": "SKU-001",
      "ProductLocationsLimitations": [
        {
          "StockLocationId": 12,
          "StockBuffer": null,
          "StockLimit": 20
        }
      ]
    }
  ],
  "Success": true
}

Removing settings

Use DELETE /v2/offer/{channelId}/product-level-stock-limitations to remove stock buffer or limit settings for specific products and stock locations. Once removed, ChannelEngine exports the full stock value to the channel with no restriction applied.

// DELETE /v2/offer/42/product-level-stock-limitations
// Remove limitations for SKU-001 at locations 12 and 15
{
  "ProductLocations": [
    {
      "MerchantProductNo": "SKU-001",
      "StockLocationIds": [12, 15]
    }
  ]
}

Common issues

Onboarding test script

Run through these tests before going live to confirm that your offer integration is working end-to-end. Work through them in order and share your results with your ChannelEngine implementation contact before sign-off.

Test 1 — Submit a basic offer (no stock locations)

Goal: confirm that stock and price can be submitted for a product using the default endpoint.

1. Ensure a test product exists in ChannelEngine (created via POST /v2/products). Note its MerchantProductNo.
2. Call PUT /v2/offer with a stock and price value for your test product. Expected result: HTTP 200, Success: true.
3. Check the response payload. A 200 response with Success: true confirms the update was processed. You do not need to re-fetch the stock level — the response is the source of truth for whether the update landed correctly. Expected result: HTTP 200, Success: true, no errors in the response body.
4. Submit a price-only update by calling PUT /v2/offer with only MerchantProductNo and Price — no Stock field. Expected result: HTTP 200, stock is unchanged, only the price is updated.

Test 2 — Create stock locations

Goal: confirm that your warehouses can be created as stock locations in ChannelEngine.

1. Call POST /v2/stocklocations for your first warehouse. Set IsDefault: true and include a clear name (e.g.: "Warehouse NL"). Expected result: HTTP 200, Success: true.
2. Repeat for any additional warehouses. Set IsDefault: false for all non-primary locations. Expected result: HTTP 200 for each call.

Test 3 — Retrieve stock location IDs

Goal: confirm that you can retrieve the IDs assigned to your stock locations.

1. Call GET /v2/stocklocations and inspect the response. Expected result: your warehouses appear in the Content array with unique Id values. Any marketplace fulfilment locations (FBA, ZFS, etc.) also appear.
2. Note the Id values for each of your merchant warehouses and store them in your integration configuration.

Test 4 — Submit stock per location

Goal: confirm that stock can be submitted per warehouse using the location IDs retrieved in Test 3.

1. Call PUT /v2/offer/stock for one test product. Include a StockLocations array with an entry for each of your warehouses, using the IDs from Test 3. Expected result: HTTP 200, Success: true.
2. Verify using GET /v2/offer/stock — filter by your test SKU and the stock location IDs. Expected result: stock at each location matches what you submitted, and the aggregated total across locations is correct.
3. Confirm on ChannelEngine — navigate to the product's offer details and verify the stock per warehouse is displayed correctly. Expected result: each warehouse shows the stock value you submitted.

Sign-off checklist

Before going live, confirm all of the following with your ChannelEngine implementation contact:

• Stock and price are submitted via PUT /v2/offer or PUT /v2/offer/stock — not via the Products endpoints.
• Offer updates are batched — multiple products are sent in a single call, not one call per product.
• A basic offer (stock and price) has been successfully submitted and verified via GET /v2/offer/stock.
• If applicable: all warehouses have been created as stock locations with unique names.
• If applicable: exactly one stock location is set as the default.
• If applicable: stock location IDs are stored in your integration — not fetched on every stock update.
• If applicable: per-location stock has been submitted and verified. The aggregated total across locations is correct.
• If applicable: price updates are sent separately via PUT /v2/offer when using PUT /v2/offer/stock for stock.

Next steps

• Managing products via the Merchant API — submit product content, hierarchies, and bundles.
• Freezing a product — temporarily set stock to 0 across all channels using the freeze mechanism.
• Channel mapping and offer settings — configure how offer data maps to individual channel requirements.
• Authentication and rate limits — Merchant API key setup and request throttling.