Multi-inventory

Overview

When the multi-inventory feature is active on the store, Yep distributes each product's stock across multiple warehouses (physical store, main depot, distribution centers etc.). This page covers the four related REST API surfaces: Warehouses (warehouse registry), Stockitems (per-warehouse stock with automatic aggregation), Products (with stock_data.warehouses) and the impact on Orders (warehouses per order item).

General rules

Conventions shared by every multi-inventory endpoint. Base URL in examples: /api2. Protected endpoints require Authorization: Bearer {{token}} and Content-Type: application/json on POST/PATCH verbs.

• These endpoints are part of the multi-inventory feature and inherit OAuth authentication, deterministic pagination and the Yep REST response shape.
• Listings accept page, limit, include_pagination and filters via query string or JSON body.
• The warehouses field accepts two shapes: map {code: qty} (compact shortcut) or list [{code, qty}] (more explicit; useful when the integration works with arrays).
• When warehouses is sent, the product's aggregated total stock is recalculated automatically by the module's model. There is no need to send qty separately.

Warehouses

Store warehouse registry. By default, lists active warehouses only; use include_inactive=true for auditing or for integrations that need to see all of them.

GET /api2/warehouses?page=1&limit=50&include_pagination=1
Authorization: Bearer {{token}}

GET /api2/warehouses?code=main_depot
Authorization: Bearer {{token}}

{
  "success": true,
  "warehouse": {
    "warehouse_id": 1,
    "code": "main_depot",
    "name": "Main depot",
    "status": 1
  }
}

{
  "success": true,
  "page": 1,
  "limit": 50,
  "total": 4,
  "last_page": 1,
  "has_next": false,
  "warehouses": [
    {"warehouse_id": 1, "code": "main_depot", "name": "Main depot",  "status": 1},
    {"warehouse_id": 2, "code": "store_sp",   "name": "São Paulo",   "status": 1},
    {"warehouse_id": 3, "code": "store_rj",   "name": "Rio store",   "status": 1},
    {"warehouse_id": 4, "code": "dc_north",   "name": "DC North",    "status": 0}
  ]
}

Stockitems

Query and update stock per warehouse. The response always includes a warehouses field with the breakdown per warehouse and the aggregated total qty.

GET /api2/stockitems?page=1&limit=50&include_pagination=1
Authorization: Bearer {{token}}

GET /api2/stockitems?id=456
Authorization: Bearer {{token}}

GET /api2/stockitems?product_id=123
Authorization: Bearer {{token}}

GET /api2/stockitems?sku=PRODUCT-001
Authorization: Bearer {{token}}

{
  "sku": ["PRODUCT-001", "PRODUCT-002"],
  "include_pagination": true
}

{
  "success": true,
  "stockitem": {
    "item_id": 456,
    "stock_item_id": 456,
    "stock_id": 1,
    "product_id": 123,
    "sku": "PRODUCT-001",
    "name": "Product 001",
    "qty": 15,
    "is_in_stock": 1,
    "manage_stock": 1,
    "use_config_manage_stock": 1,
    "backorders": 0,
    "min_qty": 0,
    "min_sale_qty": 1,
    "warehouses": {
      "main_depot": 10,
      "store_sp": 5
    }
  }
}

PATCH /api2/stockitems
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "id": 456,
  "warehouses": {
    "main_depot": 10,
    "store_sp": 5
  }
}

PATCH /api2/stockitems
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "sku": "PRODUCT-001",
  "warehouses": {
    "main_depot": 10,
    "store_sp": 5
  }
}

PATCH /api2/stockitems
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "product_id": 123,
  "stock_data": {
    "is_in_stock": 1,
    "manage_stock": 1,
    "warehouses": {
      "main_depot": 10
    }
  }
}

PATCH /api2/stockitems
Authorization: Bearer {{token}}
Content-Type: application/json

[
  {
    "sku": "PRODUCT-001",
    "warehouses": {
      "main_depot": 10
    }
  },
  {
    "sku": "PRODUCT-002",
    "warehouses": [
      {"code": "main_depot", "qty": 3},
      {"code": "store_sp", "qty": 2}
    ]
  }
]

Warehouses inside Products

When the multi-inventory feature is active, the Products endpoints start including stock_data.warehouses in the responses, preserving compatibility with the stock_data semantics already consumed by catalog integrations.

GET /api2/products?type=sku&id=PRODUCT-001
Authorization: Bearer {{token}}

GET /api2/products?page=1&limit=50&include_pagination=1
Authorization: Bearer {{token}}

{
  "success": true,
  "product": {
    "product_id": 123,
    "sku": "PRODUCT-001",
    "name": "Product 001",
    "stock_data": {
      "qty": 15,
      "is_in_stock": 1,
      "warehouses": {
        "main_depot": 10,
        "store_sp": 5
      }
    }
  }
}

Warehouses inside order items

When the multi-inventory feature is active, the Orders endpoints include a warehouses field inside each item of the response — indicating which warehouses fulfilled each quantity.

GET /api2/order?id=100
Authorization: Bearer {{token}}

{
  "success": true,
  "order": {
    "order_id": 100,
    "increment_id": "100000100",
    "items": [
      {
        "item_id": 10,
        "sku": "PRODUCT-001",
        "qty_ordered": 2,
        "warehouses": {
          "main_depot": 2
        }
      }
    ]
  }
}

Supported usage patterns

Tested and certified combinations for the multi-inventory API.

Integration recommendations

Recommended

• Cache the listing of /api2/warehouses — the registry rarely changes, and every stock call can reuse the list.
• Use the list shape ([{code, qty}]) when the integration serializes data from a relational database; use the map shape ({code: qty}) when the data already arrives as a dictionary.
• For high-volume syncs, prefer the batch PATCH — it minimizes auth and logging overhead.
• Read warehouses from order items to feed your OMS/WMS with which warehouse fulfills each line.

Avoid

• Sending the total qty together with warehouses — the total will be overridden by the module's recalculation.
• Using non-ASCII characters in warehouse codes for environments that serialize URLs — prefer slugs (main_depot rather than Depósito Padrão).
• Updating warehouses in a loop (1 PATCH per SKU) when the batch already covers it — generates contention on the aggregated stock.

Common errors