Inventory (admin API)

Admin routes of the inventory module. Every route needs a staff session and the permission named on it; send X-Resolve-Locale: false to receive every locale of a translatable field for editing.

GET /v1/admin/inventory

List stock levels

Parameters:

• locationId in query (string, optional).
• page in query (number, min 1, optional).
• pageSize in query (number, min 1, max 100, optional).
• sortBy in query ("onHand", "reserved", "updatedAt", optional).
• sortOrder in query ("asc", "desc", optional).
• stockStatus in query ("IN_STOCK", "LOW_STOCK", "OUT_OF_STOCK", optional).
• variantId in query (string, optional).

Responses:

• 200: Stock levels retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.

PATCH /v1/admin/inventory/adjust

Adjust inventory stock

Request body: AdjustInventoryAdminDto.

Responses:

• 200: Inventory adjusted.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Variant not found.

GET /v1/admin/inventory/alerts

List low/out-of-stock alerts

Parameters:

• page in query (string, optional).
• pageSize in query (string, optional).

Responses:

• 200: Alerts retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.

GET /v1/admin/inventory/locations

List inventory locations

Parameters:

• page in query (string, optional).
• pageSize in query (string, optional).

Responses:

• 200: Locations retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.

POST /v1/admin/inventory/locations

Create inventory location

Request body: CreateInventoryLocationAdminDto.

Responses:

• 201: Location created.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.

DELETE /v1/admin/inventory/locations/{id}

Delete inventory location

Parameters:

• id in path (string, required).

Responses:

• 204: Location deleted.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Location not found.
• 409: Location has stock.

PATCH /v1/admin/inventory/locations/{id}

Update inventory location

Parameters:

• id in path (string, required).

Request body: UpdateInventoryLocationAdminDto.

Responses:

• 200: Location updated.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Location not found.

GET /v1/admin/inventory/movements

List inventory movements

Parameters:

• dateFrom in query (string, optional).
• dateTo in query (string, optional).
• locationId in query (string, optional).
• page in query (number, min 1, optional).
• pageSize in query (number, min 1, max 100, optional).
• sortBy in query ("createdAt", "quantity", "type", optional).
• sortOrder in query ("asc", "desc", optional).
• type in query ("ADJUSTMENT", "RESERVATION", "RESERVATION_RELEASE", "RETURN", "SALE", "TRANSFER", optional).
• variantId in query (string, optional).

Responses:

• 200: Movements retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.

POST /v1/admin/inventory/transfer

Transfer inventory between locations

Request body: TransferInventoryAdminDto.

Responses:

• 200: Inventory transferred.
• 400: Invalid input.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Location or variant not found.

GET /v1/admin/inventory/variant/{variantId}

Get variant stock levels

Parameters:

• variantId in path (string, required).

Responses:

• 200: Stock levels retrieved.
• 401: Unauthorized.
• 403: Insufficient permissions.
• 404: Variant not found.

Schemas

AdjustInventoryAdminDto

• variantId (string, required).
• locationId (string, required).
• quantity (number, optional).
• setTo (number, min 0, optional).
• expectedOnHand (number, min 0, optional).
• reason ("CORRECTION", "DAMAGE", "OTHER", "RECEIVED", "RECOUNT", "RETURN_DAMAGED", "RETURN_RESTOCK", "SHRINKAGE", required).
• notes (string, max length 500, optional).

CreateInventoryLocationAdminDto

• name (string, max length 100, required).
• code (string, pattern ^[A-Z0-9_-]{1,20}$, required).
• isActive (boolean, optional).

TransferInventoryAdminDto

• variantId (string, required).
• fromLocationId (string, required).
• toLocationId (string, required).
• quantity (number, min 1, required).
• notes (string, max length 500, optional).

UpdateInventoryLocationAdminDto