{
"fboAccountId": "m97fbo456",
"lines": [{ "productId": "jh7prod123", "quantityDeclared": 10 }],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123"
}
{
"fboAccountId": "m97fbo456",
"lines": [{ "productId": "jh7prod123", "quantityDeclared": 10 }],
"carrier": "FedEx",
"trackingNumber": "794658123456"
}
{
"fboAccountId": "m97fbo456",
"lines": [{ "productId": "jh7prod123", "quantityDeclared": 10 }]
}
Inbound Shipments
Create Inbound Shipment
Announce an inbound shipment, optionally buying its label
POST
/
inbound-shipments
{
"fboAccountId": "m97fbo456",
"lines": [{ "productId": "jh7prod123", "quantityDeclared": 10 }],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123"
}
{
"fboAccountId": "m97fbo456",
"lines": [{ "productId": "jh7prod123", "quantityDeclared": 10 }],
"carrier": "FedEx",
"trackingNumber": "794658123456"
}
{
"fboAccountId": "m97fbo456",
"lines": [{ "productId": "jh7prod123", "quantityDeclared": 10 }]
}
Announces an inbound shipment and its declared contents. There are three ways to handle shipping, and the response varies accordingly:
Permission:
Without a
Buy a label with the shipment
Quote rates with Get Inbound Shipment Label Quote, 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.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
Show line properties
string
required
ID of the product being shipped. Look up catalog product IDs with List
Products.
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 Inbound Shipment Label Quote, 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": "m97fbo456",
"lines": [{ "productId": "jh7prod123", "quantityDeclared": 10 }],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123"
}
{
"fboAccountId": "m97fbo456",
"lines": [{ "productId": "jh7prod123", "quantityDeclared": 10 }],
"carrier": "FedEx",
"trackingNumber": "794658123456"
}
{
"fboAccountId": "m97fbo456",
"lines": [{ "productId": "jh7prod123", "quantityDeclared": 10 }]
}
Response
When arateId 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": "jn7shipin123",
"fboAccountId": "m97fbo456",
"organizationId": "k57orgxyz",
"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"
}
}
rateId, only shipment is returned:
{
"data": {
"shipment": {
"id": "jn7shipin123",
"fboAccountId": "m97fbo456",
"organizationId": "k57orgxyz",
"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.