Create inbound shipment · Bigblue Developers

POST/bigblue.storeapi.v1.PublicAPI/CreateInboundShipment

Creates an inbound shipment. By default it's a draft you can still edit. With finalize: true, it's sent to the warehouse in the same request.

The response includes public_appointment_url, a link to the delivery slot. Only create and update return it, so save it now.

Request body

inbound_shipmentInboundShipmentFormrequired

The shipment to create.

finalizebooleandefault false

Send the shipment to the warehouse right away.

InboundShipmentForm

supplier_shipment_idstringrequired

Your or your supplier's reference for the shipment.

At least 1 character

supplier_namestringrequired

Who is sending the goods.

At least 1 character

warehousestringrequired

Destination warehouse. Must be one of your warehouses.

Pattern^[A-Za-z]{2}-[A-Za-z]{3}-[0-9]{3}$

expected_arrival_timestringrequired

RFC 3339 UTC, for example 2026-04-02T08:00:00Z.

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

carrier_namestringrequired

The carrier delivering the shipment.

At least 1 character

line_itemsInboundShipment.LineItem[]required

At least one line. Products only.

At least 1 item

expected_loadInboundShipmentLoad

How the goods are packed. Set one of the four load types.

receive_to_orderbooleandefault false

Receive in cross-dock mode: orders can reserve the expected quantities before the shipment arrives. Can't be changed later. See Cross-docking.

idstring

Your own ID, so retries don't create duplicates. Generated if empty.

Pattern^[A-Za-z0-9]{13}$

expected_pallet_countintegerdeprecated

Use expected_load.pallet_load instead.

expected_box_countintegerdeprecated

Use expected_load.box_load instead.

Landed cost currency

unit_landed_cost uses the warehouse's valuation currency, or the default currency of the warehouse's country if none is set. The response returns it as currency. An amount that can't be parsed fails with invalid_argument.

Lot fields

Products with track_lots need a lot_code on their line. Products with track_lot_expiry also need a lot_expiration_date. If one is missing, the request fails with invalid_argument.

Responses

200The shipment was created.

inbound_shipmentInboundShipment

The new shipment, with its id, currency, status and public_appointment_url. Doesn't include appointment.

400A field is invalid, the warehouse is unknown, or a landed cost can't be parsed.

{ "code": "invalid_argument", "msg": "invalid warehouse FR-CDG-1" }

404A line references a product that doesn't exist.

{ "code": "not_found", "msg": "product BGBL-MUGCLA-WHIT not found" }

409A shipment with this ID already exists.

{ "code": "already_exists", "msg": "inbound shipment already exists" }

POST/bigblue.storeapi.v1.PublicAPI/CreateInboundShipment

Request: pallets, sent right away

{
  "finalize": true,
  "inbound_shipment": {
    "supplier_shipment_id": "PO-2026-0412",
    "supplier_name": "Coimbra Textiles",
    "warehouse": "FR-CDG-001",
    "expected_arrival_time": "2026-04-02T08:00:00Z",
    "carrier_name": "DB Schenker",
    "expected_load": {
      "pallet_load": {
        "homogeneous_pallet_count": 4,
        "heterogeneous_pallet_count": 1
      }
    },
    "line_items": [
      {
        "product": "BGBL-ESPSRT-SMAL",
        "quantity": 600,
        "unit_landed_cost": "7.35"
      },
      {
        "product": "BGBL-ESPSRT-MEDI",
        "quantity": 900,
        "unit_landed_cost": "7.35"
      }
    ]
  }
}

200

{
  "inbound_shipment": {
    "id": "IB7K2M9XQ4P1C",
    "supplier_shipment_id": "PO-2026-0412",
    "supplier_name": "Coimbra Textiles",
    "warehouse": "FR-CDG-001",
    "expected_arrival_time": "2026-04-02T08:00:00Z",
    "carrier_name": "DB Schenker",
    "currency": "EUR",
    "line_items": [
      {
        "product": "BGBL-ESPSRT-SMAL",
        "quantity": 600,
        "unit_landed_cost": "7.35"
      },
      {
        "product": "BGBL-ESPSRT-MEDI",
        "quantity": 900,
        "unit_landed_cost": "7.35"
      }
    ],
    "status": {
      "code": "TRANSMITTED",
      "total_expected_count": 1500
    },
    "create_time": "2026-03-14T09:30:00Z",
    "public_appointment_url": "https://inbounds.bigblue.co/a/IB7K2M9XQ4P1C"
  }
}

Request: boxes, lot-tracked

{
  "inbound_shipment": {
    "supplier_shipment_id": "PO-2026-0413",
    "supplier_name": "Nordic Roasters",
    "warehouse": "FR-CDG-001",
    "expected_arrival_time": "2026-04-05T09:00:00Z",
    "carrier_name": "DHL Freight",
    "expected_load": {
      "box_load": { "homogeneous_box_count": 40 }
    },
    "line_items": [
      {
        "product": "BGBL-COFBEA-1KGX",
        "quantity": 480,
        "lot_code": "L2026-04",
        "lot_expiration_date": "2027-04-30",
        "block_for_quality_control": true
      }
    ]
  }
}