Inventory

UI-only feature. Inventory management (stock buckets, lots, movements, allocation) is handled through the Borderbolt web interface, not through the REST API. This page documents the concepts and the allocation flow that is triggered automatically when you submit a warehouse exit declaration via the API.

Overview

The inventory module tracks goods stored in customs warehouses. Each stock bucket groups all lots that share the same declarant, customer, warehouse permit, SKU code, and commodity code. Each lot records its own quantity balance and an append-only movement history.

Stock Bucket Fields

Field	Type	Description
`declarant_eori`	string	Declarant EORI number
`customer_id`	integer	Customer the goods belong to
`warehouse_licence`	string	Warehouse permit number
`sku_code`	string	Internal SKU code
`commodity_code`	string	10-digit commodity (HS) code
`description`	string	Plain-language goods description
`country_of_origin`	string	2-letter ISO country code
`quantity_unit`	string	Unit of measure (e.g. `NAR`)
`total_quantity`	number	Sum of all opening quantities across lots
`reserved_quantity`	number	Quantity reserved by pending declarations
`available_quantity`	number	Quantity free to allocate
`drawn_quantity`	number	Quantity drawn down by accepted declarations

Movement Types

Type	Description
`credit`	Goods added to a lot (placement accepted)
`reserve`	Quantity reserved when a declaration line is allocated
`release_reservation`	Reservation released when an allocation is cleared
`debit`	Quantity drawn down after a declaration is accepted by customs
`adjust`	Manual correction after a physical stock count

Stock Allocation and Declaration Submit

When you submit a warehouse exit declaration (e.g. procedure 40/71) via the API, Borderbolt automatically draws down the correct quantity from inventory using FIFO allocation. The allocation creates a reserve movement at declaration submit time and converts it to a debit movement when Dutch Customs accepts the declaration.

The previous-document references added to the declaration line (the CLE / Z document references pointing back to the placement declaration) are populated automatically from the allocated lot.

Allocation Behaviour

FIFO by default: the oldest lot with sufficient available stock is selected automatically.
Manual override: in the Borderbolt UI you can choose a specific lot before submitting, or reallocate a line while the declaration is still a draft.
Release: allocations can be released in the UI while the consuming declaration is still a draft. Once Dutch Customs has accepted the declaration the allocation is final.

Starting Inventory

If you have goods already on hand when you start using Borderbolt (without a backing placement declaration), create a starting inventory record in the UI. This creates an initial lot that can be allocated to future warehouse exit declarations exactly like a regular placement lot.

Errors

The following errors may appear in API responses when a declaration submit triggers an allocation:

Code	HTTP	Meaning
`INSUFFICIENT_STOCK`	422	The line quantity exceeds the available stock. Adjust the line quantity or release goods first.
`LOT_NOT_FOUND`	404	The manually selected lot does not exist or belongs to another organisation.
`LOT_DEPLETED`	422	The lot is fully drawn down and cannot accept new allocations.
`ALLOCATION_FINALISED`	422	The allocation cannot be released because the consuming declaration has already been accepted by Dutch Customs.

Warehouse & Chain Procedures — create warehouse entry and exit declarations via the API
Declaration Submit API — submit a declaration to Dutch Customs
Webhooks — receive declaration.accepted and declaration.released events to trigger downstream stock updates