Inbound Shipments

An inbound shipment is a package on its way to the vault for one of your FBO accounts. You announce it with the products and quantities it should contain; Beach receives it, checks the contents, and accepts them. Inventory items are created at acceptance. Before that, the shipment is the only record the API has of the pieces.

Terms

Term	Meaning
Inbound shipment	One package (or set of packages under one tracking number) headed to the vault for one FBO account.
Line	A declared product and quantity. Create sends `lines`. Get and list return them as `lineItems` when `includeLineItems=true`.
Label	A carrier label bought through Beach. Quote rates first, then pass the `rateId` when you create the shipment.
Packing slip	A printable PDF returned on create. Goes inside the box. Includes the label when one was bought.
Return shipment	An inbound shipment carrying items that previously shipped out. Same object, same flow; the items come back as `in_vault`.

Model

model InboundShipment {
  id              String
  fboAccountId    String
  organizationId  String
  status          InboundShipmentStatus
  carrier         String?
  trackingNumber  String?
  shipmentNotes   String?
  receivedAt      DateTime?
  createdAt       DateTime

  fboAccount      FboAccount
  lines           InboundShipmentLine[]
}

model InboundShipmentLine {
  productId         String
  quantityDeclared  Int
  quantityReceived  Int?
  quantityAccepted  Int?
  quantityRejected  Int?
  inventoryItemIds  String[]           // filled at acceptance

  product           Product
  inventoryItems    InventoryItem[]
}

The shipment is scoped to one FBO account. Everything in the box lands on that account. To receive for several customers, create one shipment per account.

Full field reference is on Get Inbound Shipment.

Statuses

Status	Meaning
`created`	Announced, no carrier or tracking yet.
`in_transit`	Has a tracking number. Either you bought a label or supplied your own.
`processing`	At the vault. Received and being checked against the declared lines.
`accepted`	Closed with accepted units and no rejected units. Declared quantity can be higher than accepted quantity. Inventory items exist for the accepted units.
`rejected`	Closed with no accepted units. No inventory items.
`cancelled`	Cancelled before it reaches the vault.

There is no endpoint to add tracking after create. A created shipment stays created until it is cancelled or it arrives. To ship with tracking, cancel it and create again with carrier and trackingNumber, or with a rateId. There is no partially_accepted status. A shipment does not close while some units are accepted and others are rejected. After accepted or rejected, pass includeLineItems=true and read quantityAccepted, quantityRejected, and inventoryItemIds. Status changes are pushed as inbound_shipment.status_changed webhook events. When items are created, each fires inventory.vaulted and inventory.status_changed to in_vault. Those two inventory events are the same moment.

Three ways to ship

You want to	Send on create	Starts in
Buy a label through Beach	`rateId` from a label quote	`in_transit`
Use your own carrier account	`carrier` + `trackingNumber`	`in_transit`
Announce without tracking	neither	`created`

Whichever you choose, ship to the account’s intake address. The vault ID in that address is how the package gets matched to the right FBO account.

Get Started

Terms

Model

Statuses

Three ways to ship

Endpoints

​Terms

​Model

​Statuses

​Three ways to ship

​Endpoints

Terms

Model

Statuses

Three ways to ship

Endpoints