> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beachdepository.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inbound Shipments

> How inventory gets into the vault

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

```prisma theme={null}
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[]
}
```

<Info>
  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.
</Info>

Full field reference is on [Get Inbound Shipment](/api-reference/inbound-shipments/get).

## 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.                                                                                                                  |

```mermaid theme={null}
stateDiagram-v2
    [*] --> created: Create without shipping
    [*] --> in_transit: Create with label or tracking
    created --> cancelled: Cancel
    created --> processing: Arrives
    in_transit --> cancelled: Cancel
    in_transit --> processing: Arrives
    processing --> accepted
    processing --> rejected
```

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](/guides/webhooks) 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](/api-reference/inbound-shipments/get-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](/api-reference/fbo-accounts/get-intake-address). The vault ID in that address is how the package gets matched to the right FBO account.

## Endpoints

* [List Inbound Shipments](/api-reference/inbound-shipments/list)
* [Get Inbound Shipment](/api-reference/inbound-shipments/get)
* [Get Label Quote](/api-reference/inbound-shipments/get-label-quote)
* [Create Inbound Shipment](/api-reference/inbound-shipments/create)
* [Cancel Inbound Shipment](/api-reference/inbound-shipments/cancel)