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

# Create Inbound Shipment

> Announce an inbound shipment, optionally buying its label

Announces an inbound shipment and its declared contents. There are three ways to handle shipping, and the response varies accordingly:

<CardGroup cols={1}>
  <Card title="Buy a label with the shipment" icon="tag">
    Quote rates with [Get Label Rates](/api-reference/labels/get-rates), then pass the chosen
    `rateId` here. The label is purchased, tracking is attached, the shipment starts in
    `in_transit`, and the response includes the label plus a printable packing slip with the label
    merged into it.
  </Card>

  <Card title="Ship with your own label" icon="truck">
    Pass `carrier` and `trackingNumber`. The shipment starts in `in_transit` and is tracked, but no
    label is purchased.
  </Card>

  <Card title="Decide shipping later" icon="clock">
    Pass neither. The shipment is created in `pending`.
  </Card>
</CardGroup>

**Permission:** `inbound_shipments:create`

## Request body

<ParamField body="fboAccountId" type="string" required>
  ID of the FBO account the shipment belongs to.
</ParamField>

<ParamField body="lines" type="array" required>
  Declared contents of the shipment. At least one line is required.

  <Expandable title="line properties">
    <ParamField body="productId" type="string" required>
      ID of the product being shipped.
    </ParamField>

    <ParamField body="quantityDeclared" type="integer" required>
      Declared quantity for this product. Must be at least 1.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="shipmentNotes" type="string">
  Free-form notes about the shipment. Included on the packing slip.
</ParamField>

<ParamField body="rateId" type="string">
  The `id` of a rate returned by [Get Label Rates](/api-reference/labels/get-rates), to buy that
  label with the shipment. The insured value and pricing come from the quote, so there's nothing to
  echo back. The rate must have been quoted for the same `fboAccountId`, and quotes stay valid for
  15 minutes. Cannot be combined with `carrier`/`trackingNumber`.
</ParamField>

<ParamField body="carrier" type="string">
  Carrier name, when shipping with your own label. Must be provided together with `trackingNumber`,
  and cannot be combined with `rateId`.
</ParamField>

<ParamField body="trackingNumber" type="string">
  Tracking number, when shipping with your own label. Must be provided together with `carrier`.
</ParamField>

<RequestExample>
  ```json Buying a label theme={null}
  {
    "fboAccountId": "fbo_abc123",
    "lines": [{ "productId": "prod_abc123", "quantityDeclared": 10 }],
    "shipmentNotes": "10x 1oz Gold Eagles",
    "rateId": "rate_abc123"
  }
  ```

  ```json Your own label theme={null}
  {
    "fboAccountId": "fbo_abc123",
    "lines": [{ "productId": "prod_abc123", "quantityDeclared": 10 }],
    "carrier": "FedEx",
    "trackingNumber": "794658123456"
  }
  ```

  ```json No shipping yet theme={null}
  {
    "fboAccountId": "fbo_abc123",
    "lines": [{ "productId": "prod_abc123", "quantityDeclared": 10 }]
  }
  ```
</RequestExample>

## Response

When a `rateId` was provided, `label` and `packingSlipUrl` are included. `packingSlipUrl` is a printable PDF containing the packing slip followed by the shipping label — print it, include the slip in the box, and affix the label.

```json theme={null}
{
  "data": {
    "shipment": {
      "id": "ship_in_abc123",
      "fboAccountId": "fbo_abc123",
      "organizationId": "org_abc123",
      "status": "in_transit",
      "shipmentNotes": "10x 1oz Gold Eagles",
      "carrier": "FedEx",
      "trackingNumber": "794658123456",
      "createdAt": "2025-04-05T16:00:00Z"
    },
    "label": {
      "purchaseId": "lblpur_abc123",
      "trackingNumber": "794658123456",
      "labelUrl": "https://files.beachdepository.com/labels/lblpur_abc123.pdf"
    },
    "packingSlipUrl": "https://files.beachdepository.com/slips/ship_in_abc123.pdf"
  }
}
```

Without a `rateId`, only `shipment` is returned:

```json theme={null}
{
  "data": {
    "shipment": {
      "id": "ship_in_abc123",
      "fboAccountId": "fbo_abc123",
      "organizationId": "org_abc123",
      "status": "pending",
      "createdAt": "2025-04-05T16:00:00Z"
    },
    "packingSlipUrl": "https://files.beachdepository.com/slips/ship_in_abc123.pdf"
  }
}
```

<Warning>
  If the label purchase fails, the shipment is cancelled and a `VALIDATION_ERROR` is returned, so no
  half-shipped record is left behind. Request rates again and retry the whole call.
</Warning>