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

# Models

> The objects the API exposes, how they relate, and how an item moves through custody

## Objects

| Object                | Belongs to   | Description                                                                                                                                                                          |
| --------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Organization**      | —            | Your account. Everything below is scoped to it.                                                                                                                                      |
| **FBO account**       | Organization | An account holder. Inventory is owned here. Each organization has one primary FBO account (`isPrimary: true`), created with the organization, which is the default inventory holder. |
| **Product**           | —            | Catalog entry. Every inventory item is an instance of a product.                                                                                                                     |
| **Inbound shipment**  | FBO account  | Items being sent to the vault. Creates inventory items when accepted.                                                                                                                |
| **Inventory item**    | FBO account  | One physical item in the vault.                                                                                                                                                      |
| **Transfer**          | Organization | Moves inventory items from one FBO account to another.                                                                                                                               |
| **Outbound request**  | FBO account  | A request to ship inventory items out.                                                                                                                                               |
| **Outbound shipment** | FBO account  | The carrier shipment created once a request is picked.                                                                                                                               |
| **Return shipment**   | FBO account  | Items coming back after an outbound shipment. Handled like an inbound shipment.                                                                                                      |

## Relations

```mermaid theme={null}
flowchart LR
    ORG[Organization]
    FBO[FBO account]
    PRODUCT[Product]
    INBOUND[Inbound shipment]
    ITEM[Inventory item]
    TRANSFER[Transfer]
    REQUEST[Outbound request]
    SHIPMENT[Outbound shipment]
    RETURN[Return shipment]

    ORG -->|has many| FBO
    ORG -->|one primary| FBO
    FBO -->|has many| INBOUND
    FBO -->|owns| ITEM
    FBO -->|has many| REQUEST
    INBOUND -->|creates on acceptance| ITEM
    PRODUCT -.->|instance of| ITEM
    TRANSFER -->|from / to| FBO
    TRANSFER -->|moves| ITEM
    REQUEST -->|references| ITEM
    REQUEST -->|fulfilled by| SHIPMENT
    SHIPMENT -->|ships| ITEM
    SHIPMENT -->|returned via| RETURN
    RETURN -->|puts back| ITEM
```

## Custody lifecycle

Before acceptance, status lives on the inbound shipment. After acceptance, it lives on the inventory item. Outbound adds a request and a shipment alongside the item.

```mermaid theme={null}
flowchart TD
    subgraph inbound["Inbound"]
        direction LR
        I1[Shipment created] --> I2[In transit] --> I3[Processing]
        I3 --> I5[Accepted]
        I3 --> I6[Rejected]
    end

    I5 -->|inventory items created| V

    subgraph vault["In custody"]
        V[in_vault]
        V -->|optional, while approved| T[pending_transfer]
        T -->|transfer completed, item now on destination FBO account| V
    end

    subgraph outbound["Outbound"]
        V -->|outbound request created, item stays in_vault| R[Request pending review]
        R -->|rejected or cancelled| V
        R -->|approved and picked| P[pending_outbound]
        P -->|shipped| S[shipped_out]
    end

    subgraph return["Return"]
        S -->|return shipment accepted| V
    end
```

### Where to watch

| Stage             | Object                                 | Status field                                                                       | Webhook                                                        |
| ----------------- | -------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| Inbound           | Inbound shipment                       | `status`                                                                           | `inbound_shipment.status_changed`                              |
| Vaulted           | Inventory item                         | `status` = `in_vault`                                                              | `inventory.vaulted`                                            |
| Transfer          | Transfer, then inventory item          | `status`; item may be `pending_transfer`. Ownership moves at `transfer.completed`. | `transfer.status_changed`, `transfer.completed`                |
| Outbound request  | Outbound request                       | `status`; item keeps `in_vault` with `openOutboundRequestId` set                   | `outbound_request.status_changed`                              |
| Outbound shipment | Outbound shipment, then inventory item | `status`; item moves `pending_outbound` → `shipped_out`                            | `outbound_shipment.status_changed`, `inventory.status_changed` |
| Return            | Inventory item                         | back to `in_vault`                                                                 | `inventory.status_changed`                                     |

Full status lists are on each object's page: [Inventory](/concepts/inventory), [Inbound shipments](/concepts/inbound-shipments), [Transfers](/concepts/transfers), [Outbound requests](/concepts/outbound-requests), [Outbound shipments](/concepts/outbound-shipments). Events: [Webhooks](/guides/webhooks).