Outbound Requests - Beach Depository

An outbound request asks Beach to ship specific inventory items out of the vault to an address. It is the intent, not the shipment. The items stay in_vault until the request is approved and the pieces are picked; at that point an outbound shipment is created and carries the carrier tracking.

Terms

Term	Meaning
Outbound request	A list of `in_vault` items on one FBO account, a destination, and a shipping preference.
Destination address	Where the package goes. Optional on create. A quote is filled in only when it is present. If you omit it, vault staff set it before the label is bought. There is no API check that rejects review or pick for a missing address.
Shipping preference	`cheapest` (default) picks the lowest-cost insured service. `selected` names a `serviceCode`. Signature type is separate.
Quote	The price Beach resolves after create. Never accepted from you; read it back on the request once it is filled in.
Outbound shipment	Created when the request is picked. Listed in `outboundShipmentIds`. Tracking lives there.

Model

model OutboundRequest {
  id                   String
  fboAccountId         String
  organizationId       String
  status               OutboundRequestStatus
  totalItems           Int
  approvedBySystem     Boolean
  notes                String?
  destinationAddress   Address?
  shipping             ShippingPreference     // mode, signatureType, quote once resolved
  outboundShipmentIds  String[]               // empty until picked
  createdAt            DateTime

  fboAccount           FboAccount
  items                OutboundRequestItem[]  // one per inventory item
  outboundShipments    OutboundShipment[]
}

Creating a request does not change item status. Each item gets openOutboundRequestId set so you can show “requested” in your UI, but it is still in_vault and still counts toward the account’s holdings until it is picked.

Full field reference is on Get Outbound Request.

Statuses

Status	Meaning
`pending_review`	Created, awaiting vault staff review. Cancellable. There is no `approve: true` on create. `approvedBySystem` stays `false`.
`processing`	Approved and being picked and packed. Items move to `pending_outbound` when picked.
`rejected`	Rejected on review. Items stay `in_vault`, `openOutboundRequestId` cleared.
`cancelled`	Cancelled by you before it is processing. Items stay `in_vault`.
`fulfilled`	Shipped. Items are `shipped_out`. Follow the shipment for delivery.

Status changes are pushed as outbound_request.status_changed webhook events.

Endpoints