Create Inbound Shipment

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

Buy a label with the shipment

Quote rates with Get Label 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.

Ship with your own label

Pass carrier and trackingNumber. The shipment starts in in_transit and is tracked, but no label is purchased.

Decide shipping later

Pass neither. The shipment is created in pending.

Permission: inbound_shipments:create

Request body

string

required

ID of the FBO account the shipment belongs to.

array

required

Declared contents of the shipment. At least one line is required.

Show line properties

string

required

ID of the product being shipped.

integer

required

Declared quantity for this product. Must be at least 1.

string

Free-form notes about the shipment. Included on the packing slip.

string

The id of a rate returned by Get Label 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.

string

Carrier name, when shipping with your own label. Must be provided together with trackingNumber, and cannot be combined with rateId.

string

Tracking number, when shipping with your own label. Must be provided together with carrier.

{
  "fboAccountId": "fbo_abc123",
  "lines": [{ "productId": "prod_abc123", "quantityDeclared": 10 }],
  "shipmentNotes": "10x 1oz Gold Eagles",
  "rateId": "rate_abc123"
}

{
  "fboAccountId": "fbo_abc123",
  "lines": [{ "productId": "prod_abc123", "quantityDeclared": 10 }],
  "carrier": "FedEx",
  "trackingNumber": "794658123456"
}

{
  "fboAccountId": "fbo_abc123",
  "lines": [{ "productId": "prod_abc123", "quantityDeclared": 10 }]
}

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.

{
  "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:

{
  "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"
  }
}

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.

API Reference

Organization

FBO Accounts

Inventory

Inbound Shipments

Outbound Shipments

Transfers

Webhooks

Statements

Labels

Buy a label with the shipment

Ship with your own label

Decide shipping later

Request body

Response

Buy a label with the shipment

Ship with your own label

Decide shipping later

​Request body

​Response

Request body

Response