Held Shipments (Stocks)

A stock (Italian giacenza) is opened by the carrier when a shipment cannot be delivered — recipient absent, wrong address, refused parcel — and is held at the depot waiting for the sender’s instructions. The shipment status becomes held_at_depot (6) or awaiting_instructions (9).

Stocks are visible to the client with the stock.opened / stock.closed webhook events and through these endpoints.

List stocks

GET /stocks?status=open|instructed|closed|all&trackingNumber= — paginated

Query parameter	Description
`status`	`open` (default) — waiting for instructions; `instructed` — instructions sent (confirmed or not); `closed`; `all`
`trackingNumber`	Exact LDV

Stock detail

GET /stocks/{id}


{
  "id": 9812,
  "trackingNumber": "DEMO05407027",
  "shipmentId": 4454058,
  "dossierId": "GIA-2026-000123",
  "status": { "code": 0, "key": "open", "label": "Aperta" },
  "carrier": { "code": "brt", "name": "BRT", "contractCode": "brt-standard", "contractName": "BRT Standard" },
  "notes": "Destinatario assente",
  "deposit": {
    "status": "IN GIACENZA",
    "releasable": true,
    "startDate": "2026-09-05T09:12:00+02:00",
    "endDate": null,
    "motivationId": "03"
  },
  "cod": { "oldAmount": 25.5, "newAmount": null },
  "totalPrice": 0,
  "lastAction": null,
  "releasedTrackingNumber": null,
  "openedAt": "2026-09-05T09:12:00+02:00",
  "releasedAt": null,
  "createdAt": "2026-09-05T09:15:31+02:00"
}

Field	Type	Description
`id`	`integer`	Stock id — use it in `/stocks/{id}/actions`
`trackingNumber`, `shipmentId`	`string`, `integer`	Shipment the stock belongs to
`dossierId`	`string\|null`	Dossier number assigned by the carrier. After a release the carrier may reissue the LDV and open a second dossier
`status.key`	`string`	`open`, `instructed` (sent, not confirmed by the carrier), `confirmed`, `closed`
`deposit`	`object`	Raw depot information from the carrier: `status`, `releasable`, `startDate`, `endDate`, `motivationId` (carrier reason code)
`cod`	`object`	`oldAmount` — original COD; `newAmount` — COD requested with the instructions
`totalPrice`	`number`	Total cost of the actions charged for this stock
`lastAction`	`object\|null`	Last instruction sent: `action`, `actionCode`, `label`, `scheduledAt`, `confirmed`, `notes`, `createdAt`
`releasedTrackingNumber`	`string\|null`	New LDV issued by the carrier after the release
`openedAt`, `releasedAt`, `createdAt`	`datetime\|null`

Send release instructions

POST /stocks/{id}/actions

Tells the carrier what to do with the held parcel. Possible once per stock: a second call answers 409 invalid_state.

Field	Type	Required	Description
`action`	`string`	Yes	`RETRY` — deliver again · `NEWADDRESS` — deliver to a new address · `RETURN` — return to sender · `DESTROY` — destroy the parcel · `ONSITECOLLECTION` — the recipient collects it at the depot
`scheduledAt`	`date`	No	`YYYY-MM-DD` date of the new delivery attempt (default: tomorrow)
`notes`	`string` (255)	No	Notes for the carrier
`cod.oldAmount`, `cod.newAmount`	`number`	No	Change the cash on delivery amount on the redelivery
`newAddress`	`object`	For `NEWADDRESS`	`name`, `street`, `city`, `province`, `postalCode` required; `countryCode` (default `IT`), `phone`, `notes` optional

Request


{
  "action": "NEWADDRESS",
  "scheduledAt": "2026-09-08",
  "notes": "Deliver to the office",
  "newAddress": {
    "name": "Giulia Bianchi",
    "street": "Via Nazionale 5",
    "city": "Roma",
    "province": "RM",
    "postalCode": "00184",
    "countryCode": "IT",
    "phone": "+39 333 7654321"
  }
}

What happens:

The instruction is recorded and the stock becomes instructed.
On carriers with canManageStocks: true the instruction is sent to the carrier immediately; if accepted, the stock becomes confirmed and lastAction.confirmed is true. On the other carriers the platform operators forward it.
The cost of the action according to your price list is charged to the credit and added to totalPrice.

HTTP	`code`	When
`404`	`not_found`	Unknown stock or stock of another client
`409`	`invalid_state`	Instructions were already sent for this stock
`422`	`validation_failed`	Unknown `action`, missing `newAddress` for `NEWADDRESS`, …
`502`	`carrier_error`	The carrier refused the instruction; the reason is in `message`

Carriers keep parcels for a limited number of days before returning them automatically. Subscribe to stock.opened to react in time.