BigblueDevelopers

Inbound shipments

Tell a warehouse what stock is arriving, and see what it received.

An inbound shipment describes a delivery to a Bigblue warehouse: the products and quantities, how they're packed, the carrier and the expected arrival date. The warehouse uses it to book a delivery slot and to check what arrives.

Inbound shipments are the only way to add stock. No endpoint sets quantities directly.

Operations

Create inbound shipment

Tell a warehouse what stock is arriving.

Update inbound shipment

Change a shipment before it arrives.

Get inbound shipment

See what the warehouse received.

List inbound shipments

List all inbound shipments.

Delete inbound shipment

Cancel a shipment before it arrives.

Statuses

  1. DRAFT
  2. PENDING
  3. TRANSMITTED
  4. ARRIVED
  5. OFFLOADING
  6. COMPLETE
  7. ARCHIVED
DRAFT
Created but not sent to the warehouse. You can still edit it.
PENDING
Sent, waiting for a delivery slot.
TRANSMITTED
Sent to the warehouse, which expects the delivery.
ARRIVED
At the warehouse, not yet unloaded.
OFFLOADING
Being unloaded and counted. line_progresses is filled in.
COMPLETE
Reception is finished. Received units are in inventory.
ARCHIVED
Closed.

The finalize option on create decides whether a new shipment starts as DRAFT or is sent right away.

Delivery appointments

The carrier or supplier requests a delivery slot through public_appointment_url, and the warehouse approves or refuses it. A shipment can have several requests, for example after a refusal or a reschedule. appointment shows one of them:

  • the approved request, if there is one
  • otherwise, the request that changed most recently
  • nothing, if no slot was requested yet
PENDING
Requested, waiting for the warehouse.
APPROVED
Confirmed. The goods are expected in this slot.
REFUSED
Refused by the warehouse. A new slot must be requested.
CANCELLED
Cancelled by the merchant or the supplier.

Depending on the warehouse, a slot is a time range or a whole day.

Cross-docking

By default, received goods are put away first, and only then become available to orders.

With receive_to_order: true, the shipment is received in cross-dock mode. Orders can reserve the expected quantities before the shipment arrives, and the warehouse ships them straight from the receiving dock instead of putting the goods away first.

You choose the mode when you create the shipment. It can't be changed afterwards.

The InboundShipment object

idstring
Bigblue inbound shipment ID.
Pattern^[A-Za-z0-9]{13}$
supplier_shipment_idstring

Your or your supplier's reference for the shipment. Shown to warehouse staff.

supplier_namestring
Who is sending the goods.
warehousestring
Destination warehouse, for example FR-CDG-001.
Pattern^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$
expected_arrival_timestring

Expected arrival, in RFC 3339 UTC: 2026-04-02T08:00:00Z.

RFC 3339 in UTC, for example 2026-03-14T09:30:00Z
expected_loadInboundShipmentLoad

How the goods are packed: boxes, pallets or a container.

carrier_namestring
The carrier delivering the shipment.
line_itemsInboundShipment.LineItem[]
The products in the shipment. At least one.
currencystring

Currency of unit_landed_cost. Read-only. Set from the warehouse's valuation currency, or the default currency of the warehouse's country.

Exactly 3 characters
statusInboundShipmentStatus
Reception progress. Read-only.
create_timestring
When the shipment was created. Read-only.
RFC 3339 in UTC, for example 2026-03-14T09:30:00Z
receive_to_orderbooleandefault false

Receive the shipment in cross-dock mode. See Cross-docking. Set on create only.

appointmentInboundShipmentAppointment

The delivery slot and whether the warehouse approved it. Read-only. Only returned by get and list. See Delivery appointments.

public_appointment_urlstring

Link to book or view the delivery slot. Only returned by create and update.

delivery_note_urlstring
Link to the delivery note, once it exists. Read-only.
appointment_timestringdeprecated
Use appointment.time_slot_start_time instead.
expected_pallet_countintegerdeprecated
Use expected_load instead.
expected_box_countintegerdeprecated
Use expected_load instead.

LineItem

productstringrequired
Product ID. Bundles can't be received.
Pattern^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$
quantityintegerrequired
Units expected. Must be greater than 0.
Greater than 0
supplier_skustring
The supplier's reference for the product.
lot_codestring
Lot code. Required for products with track_lots.
Up to 20 characters
lot_expiration_datestring

Lot expiry date. Required for products with track_lot_expiry.

Date as YYYY-MM-DD
lot_expiration_timestring
Use lot_expiration_date instead.
RFC 3339 in UTC, for example 2026-03-14T09:30:00Z
block_for_quality_controlbooleandefault false

Receive the units into quality control instead of sellable stock. They appear as quality_control in inventory until released.

unit_landed_coststring

Cost per unit including freight, duties and handling, as a decimal string. Used for stock valuation. If missing, the product's value is used.

InboundShipmentLoad

Set exactly one of these fields.

box_loadBoxLoad
Boxes, not on pallets.
pallet_loadPalletLoad
Pallets, not in a container.
floor_loaded_container_loadFloorLoadedContainerLoad

A container with loose boxes.

palletized_container_loadPalletizedContainerLoad

A container with pallets.

BoxLoad

homogeneous_box_countinteger
Boxes that contain one product.
heterogeneous_box_countinteger
Boxes that contain several products.

PalletLoad

homogeneous_pallet_countinteger
Pallets with one product.
heterogeneous_pallet_countinteger
Pallets with several products.
heterogeneous_pallet_homogeneous_box_countinteger

Boxes with one product on mixed pallets.

heterogeneous_pallet_heterogeneous_box_countinteger

Boxes with several products on mixed pallets.

FloorLoadedContainerLoad

container_seal_referencestring
The container's seal number.
Up to 60 characters
box_loadBoxLoadrequired
The boxes in the container.

PalletizedContainerLoad

container_seal_referencestring
The container's seal number.
Up to 60 characters
pallet_loadPalletLoadrequired
The pallets in the container.

InboundShipmentAppointment

Read-only.

statusstring

PENDING, APPROVED, REFUSED or CANCELLED. See Delivery appointments.

time_slot_start_timestring
Start of the requested slot, RFC 3339.
time_slot_end_timestring
End of the requested slot, RFC 3339.
warehouse_approval_notestring

Instructions for the carrier, added by the warehouse when it approves the slot.

update_timestring
When the request was last created, approved, refused or cancelled.

InboundShipmentStatus

Read-only.

codestring
One of the statuses.
update_timestring
When the status last changed.
RFC 3339 in UTC, for example 2026-03-14T09:30:00Z
total_expected_countinteger
Total units declared.
total_offloaded_countinteger

Units received in good condition. Doesn't include damaged units.

total_damaged_countinteger
Units received damaged.
commentsstring[]

Notes from warehouse staff, for example about missing or damaged units.

line_progressesInboundShipmentStatus.LineProgress[]
Reception details per line.

LineProgress

productstring
Product ID.
Pattern^[A-Za-z0-9]{4}-[A-Za-z0-9]{6}-[A-Za-z0-9]{4}$
expected_countinteger
Units declared.
offloaded_countinteger
Units received in good condition.
damaged_countinteger
Units received damaged.
lot_codestring
Lot the units were received into.
Up to 20 characters
lot_expiration_datestring
Lot expiry date, YYYY-MM-DD.
Date as YYYY-MM-DD
lot_expiration_timestring
Use lot_expiration_date instead.
RFC 3339 in UTC, for example 2026-03-14T09:30:00Z

Checking a reception

When the status is COMPLETE, compare expected_count with offloaded_count + damaged_count on each line:

for (const line of shipment.status.line_progresses ?? []) {
  const received = (line.offloaded_count ?? 0) + (line.damaged_count ?? 0);
  if (received !== line.expected_count) {
    // Over or under delivery. See status.comments for details.
  }
}

Only offloaded_count becomes sellable stock. Damaged units go to damaged in inventory, and units received with block_for_quality_control go to quality_control.

Delete bundle

Delete a bundle. Its products aren't affected.

Create inbound shipment

Tell a warehouse about a delivery, as a draft or sent right away.

On this page

OperationsStatusesDelivery appointmentsCross-dockingThe InboundShipment objectLineItemInboundShipmentLoadBoxLoadPalletLoadFloorLoadedContainerLoadPalletizedContainerLoadInboundShipmentAppointmentInboundShipmentStatusLineProgressChecking a reception