Version: 2.4.0
Inventory API
Introduction
The Inventory Service is a microservice for managing product inventory across warehouses, suppliers, and locations. It provides accurate stock tracking with support for both local (internal) and supplier inventory types, bulk operations, and CSV imports.
Key Features
- Multi-type Inventory: Separate tracking for local (INTERN) and supplier inventory
- Flexible Lookup: Query inventory by product ID, SKU, or external source identifier
- Warehouse Support: Filter and scope inventory records by warehouse
- Bulk Operations: Upsert large batches of inventory records in a single request
- CSV Import: Import inventory from CSV files with configurable field mappings (via GraphQL)
- Aggregated Quantities: Computed totals including reserved, local, and supplier quantities
- Dual API: Both REST v2 and GraphQL (Apollo Federation v2) endpoints
- Multi-tenancy: All operations are scoped to the requesting tenant
API Overview
- GET
/v2/products/{lookupKey}/{key}/inventory- Get aggregated product inventory by lookup key - GET
/v2/products/{lookupKey}/{key}/inventory/warehouses/{warehouseId}- Get product inventory scoped to a warehouse - POST
/v2/inventory/search- Search inventory with filtering and pagination - GET
/v2/inventory/id/{id}- Get a single inventory record by ID - PATCH
/v2/inventory/id/{id}- Update an inventory record - DELETE
/v2/inventory/id/{id}- Delete an inventory record - POST
/v2/inventory/bulk/{lookupKey}/{inventoryType}- Bulk upsert inventory records
Lookup Keys
| Value | Description |
|---|---|
id | Product ID |
sku | Product SKU |
sourceId | External source ID (requires source query param) |
Inventory Types
| Value | Description |
|---|---|
local | Internal (INTERN) inventory — stock owned by the tenant |
supplier | Supplier inventory — stock held by an external supplier |
Authentication
All endpoints require OAuth2 authentication using the client credentials flow:
Authorization: Bearer <your-access-token>
Error Handling
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 400 | Bad request (validation errors, invalid lookup key or inventory type) |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Inventory or product not found |
| 409 | Conflict (duplicate inventory record) |
| 500 | Internal server error |
Inventory Record Structure
| Field | Type | Description | Example |
|---|---|---|---|
id | number | Auto-generated primary key | 42 |
productId | number | Associated product ID | 1001 |
quantity | number | Stock quantity | 150 |
supplier | string | Supplier name (max 35 chars). INTERN for local inventory | Acme Corp |
supplierCode | string | Supplier's product code (max 30 chars) | AC-99821 |
sku | string | Product SKU (max 30 chars) | WIDGET-L-BLU |
warehouseId | number | Warehouse ID (0 = no warehouse) | 5 |
companyId | number | Associated company ID (0 = none) | 0 |
location | string | Storage location within warehouse (max 35 chars) | Aisle-B-Shelf-3 |
costPrice | number | Cost price (decimal, 10,5 precision) | 12.99 |
notes | string | Free-text notes (max 255 chars) | Reorder at 20 units |
nextDeliveryDate | string | Expected next delivery (ISO 8601) | 2025-08-01T00:00:00.000Z |
createdAt | string | Creation timestamp (ISO 8601) | 2025-01-15T10:30:00.000Z |
lastModifiedAt | string | Last update timestamp (ISO 8601) | 2025-03-01T08:00:00.000Z |
Uniqueness constraint: Each combination of
(tenant, productId, supplier, supplierCode, location, warehouseId, companyId)must be unique. Bulk upsert uses this key to determine whether to insert or update.
Authentication
- OAuth 2.0: OAuth2
OAuth2 Authorization
Security Scheme Type: | oauth2 |
|---|---|
OAuth Flow (clientCredentials): | Token URL: https://api.helice.cloud/oauth2/token/ Scopes: |