Inbound Shipments
Create Inbound Shipment
Announce an inbound shipment, optionally buying its label
POST
/
inbound-shipments
cURL
curl --request POST \
--url https://api.beachdepository.com/v1/inbound-shipments \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123"
}'
const response = await fetch("https://api.beachdepository.com/v1/inbound-shipments", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
fboAccountId: "m97fbo456",
lines: [
{
productId: "jh7prod123",
quantityDeclared: 10,
},
],
shipmentNotes: "10x 1oz Gold Eagles",
rateId: "rate_abc123",
}),
})
const data = await response.json()
import requests
response = requests.post(
"https://api.beachdepository.com/v1/inbound-shipments",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
},
json={
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10,
},
],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123",
},
)
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://api.beachdepository.com/v1/inbound-shipments"
payload := strings.NewReader(`{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123"
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}
curl --request POST \
--url https://api.beachdepository.com/v1/inbound-shipments \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"carrier": "FedEx",
"trackingNumber": "794658123456"
}'
const response = await fetch("https://api.beachdepository.com/v1/inbound-shipments", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
fboAccountId: "m97fbo456",
lines: [
{
productId: "jh7prod123",
quantityDeclared: 10,
},
],
carrier: "FedEx",
trackingNumber: "794658123456",
}),
})
const data = await response.json()
import requests
response = requests.post(
"https://api.beachdepository.com/v1/inbound-shipments",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
},
json={
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10,
},
],
"carrier": "FedEx",
"trackingNumber": "794658123456",
},
)
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://api.beachdepository.com/v1/inbound-shipments"
payload := strings.NewReader(`{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"carrier": "FedEx",
"trackingNumber": "794658123456"
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}
{
"data": {
"shipment": {
"id": "jn7shipin123",
"fboAccountId": "m97fbo456",
"organizationId": "k57orgxyz",
"status": "created",
"shipmentNotes": "10x 1oz Gold Eagles",
"carrier": "FedEx",
"trackingNumber": "794658123456",
"createdAt": "2025-04-05T16:00:00Z"
},
"label": {
"purchaseId": "lblpur_abc123",
"carrier": "FedEx",
"service": "FedEx Ground",
"trackingNumber": "794658123456",
"labelUrl": "https://files.beachdepository.com/labels/lblpur_abc123.pdf",
"purchasedAt": "2025-04-05T16:00:05.000Z"
},
"packingSlipUrl": "https://files.beachdepository.com/slips/ship_in_abc123.pdf"
}
}
{
"data": {
"shipment": {
"id": "jn7shipin123",
"fboAccountId": "m97fbo456",
"organizationId": "k57orgxyz",
"status": "created",
"carrier": "FedEx",
"trackingNumber": "794658123456",
"createdAt": "2025-04-05T16:00:00Z"
},
"packingSlipUrl": "https://files.beachdepository.com/slips/ship_in_abc123.pdf"
}
}
The FBO account and each
A missing FBO account, or one outside this organization, is
lines[].productId must already exist. Save the returned id. Pass rateId or carrier and trackingNumber.
Buy a label with the shipment
Quote rates with Get Inbound Shipment Label
Quote, then pass the chosen
rateId here.
The response includes label and packingSlipUrl.Ship with your own label
Pass
carrier and trackingNumber. No label is purchased. The response includes
packingSlipUrl.Authorizations
string
required
Send
Bearer <token> in this header. The key needs inbound_shipments:create.Body
string
required
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. The lines’ declared value must be at or below the insured
value on that rate.string
string
cURL
curl --request POST \
--url https://api.beachdepository.com/v1/inbound-shipments \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123"
}'
const response = await fetch("https://api.beachdepository.com/v1/inbound-shipments", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
fboAccountId: "m97fbo456",
lines: [
{
productId: "jh7prod123",
quantityDeclared: 10,
},
],
shipmentNotes: "10x 1oz Gold Eagles",
rateId: "rate_abc123",
}),
})
const data = await response.json()
import requests
response = requests.post(
"https://api.beachdepository.com/v1/inbound-shipments",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
},
json={
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10,
},
],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123",
},
)
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://api.beachdepository.com/v1/inbound-shipments"
payload := strings.NewReader(`{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123"
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}
curl --request POST \
--url https://api.beachdepository.com/v1/inbound-shipments \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"carrier": "FedEx",
"trackingNumber": "794658123456"
}'
const response = await fetch("https://api.beachdepository.com/v1/inbound-shipments", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
fboAccountId: "m97fbo456",
lines: [
{
productId: "jh7prod123",
quantityDeclared: 10,
},
],
carrier: "FedEx",
trackingNumber: "794658123456",
}),
})
const data = await response.json()
import requests
response = requests.post(
"https://api.beachdepository.com/v1/inbound-shipments",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
},
json={
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10,
},
],
"carrier": "FedEx",
"trackingNumber": "794658123456",
},
)
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://api.beachdepository.com/v1/inbound-shipments"
payload := strings.NewReader(`{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"carrier": "FedEx",
"trackingNumber": "794658123456"
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}
{
"data": {
"shipment": {
"id": "jn7shipin123",
"fboAccountId": "m97fbo456",
"organizationId": "k57orgxyz",
"status": "created",
"shipmentNotes": "10x 1oz Gold Eagles",
"carrier": "FedEx",
"trackingNumber": "794658123456",
"createdAt": "2025-04-05T16:00:00Z"
},
"label": {
"purchaseId": "lblpur_abc123",
"carrier": "FedEx",
"service": "FedEx Ground",
"trackingNumber": "794658123456",
"labelUrl": "https://files.beachdepository.com/labels/lblpur_abc123.pdf",
"purchasedAt": "2025-04-05T16:00:05.000Z"
},
"packingSlipUrl": "https://files.beachdepository.com/slips/ship_in_abc123.pdf"
}
}
{
"data": {
"shipment": {
"id": "jn7shipin123",
"fboAccountId": "m97fbo456",
"organizationId": "k57orgxyz",
"status": "created",
"carrier": "FedEx",
"trackingNumber": "794658123456",
"createdAt": "2025-04-05T16:00:00Z"
},
"packingSlipUrl": "https://files.beachdepository.com/slips/ship_in_abc123.pdf"
}
}
packingSlipUrl is always returned. label is included when a rateId was provided.
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.This endpoint supports the
Idempotency-Key header.Errors
A schema failure is400 BAD_REQUEST. The message is body/<field> <reason>.
message |
|---|
body/rateId Pass rateId or carrier and trackingNumber. Update cannot attach shipping later |
body/trackingNumber carrier and trackingNumber must be provided together |
body/rateId Provide either rateId (to buy a label) or carrier/trackingNumber (your own label) |
body/lines lines must contain at least one line |
body/lines/0/quantityDeclared Too small: expected number to be >=1 |
404 NOT_FOUND with message FBO account not found.
These checks are 422 VALIDATION_ERROR. The message is exact.
message |
|---|
Product not found |
A shipment with this tracking number already exists |
Rate not found or expired — request rates again and retry with a fresh rateId |
rateId was quoted for a different fboAccountId |
Label purchase failed, shipment was cancelled — request rates again and retry |
Invalid request parameters |
⌘I
cURL
curl --request POST \
--url https://api.beachdepository.com/v1/inbound-shipments \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123"
}'
const response = await fetch("https://api.beachdepository.com/v1/inbound-shipments", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
fboAccountId: "m97fbo456",
lines: [
{
productId: "jh7prod123",
quantityDeclared: 10,
},
],
shipmentNotes: "10x 1oz Gold Eagles",
rateId: "rate_abc123",
}),
})
const data = await response.json()
import requests
response = requests.post(
"https://api.beachdepository.com/v1/inbound-shipments",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
},
json={
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10,
},
],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123",
},
)
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://api.beachdepository.com/v1/inbound-shipments"
payload := strings.NewReader(`{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"shipmentNotes": "10x 1oz Gold Eagles",
"rateId": "rate_abc123"
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}
curl --request POST \
--url https://api.beachdepository.com/v1/inbound-shipments \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data '{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"carrier": "FedEx",
"trackingNumber": "794658123456"
}'
const response = await fetch("https://api.beachdepository.com/v1/inbound-shipments", {
method: "POST",
headers: {
Authorization: "Bearer <token>",
"Content-Type": "application/json",
},
body: JSON.stringify({
fboAccountId: "m97fbo456",
lines: [
{
productId: "jh7prod123",
quantityDeclared: 10,
},
],
carrier: "FedEx",
trackingNumber: "794658123456",
}),
})
const data = await response.json()
import requests
response = requests.post(
"https://api.beachdepository.com/v1/inbound-shipments",
headers={
"Authorization": "Bearer <token>",
"Content-Type": "application/json",
},
json={
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10,
},
],
"carrier": "FedEx",
"trackingNumber": "794658123456",
},
)
package main
import (
"fmt"
"io"
"net/http"
"strings"
)
func main() {
url := "https://api.beachdepository.com/v1/inbound-shipments"
payload := strings.NewReader(`{
"fboAccountId": "m97fbo456",
"lines": [
{
"productId": "jh7prod123",
"quantityDeclared": 10
}
],
"carrier": "FedEx",
"trackingNumber": "794658123456"
}`)
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}
{
"data": {
"shipment": {
"id": "jn7shipin123",
"fboAccountId": "m97fbo456",
"organizationId": "k57orgxyz",
"status": "created",
"shipmentNotes": "10x 1oz Gold Eagles",
"carrier": "FedEx",
"trackingNumber": "794658123456",
"createdAt": "2025-04-05T16:00:00Z"
},
"label": {
"purchaseId": "lblpur_abc123",
"carrier": "FedEx",
"service": "FedEx Ground",
"trackingNumber": "794658123456",
"labelUrl": "https://files.beachdepository.com/labels/lblpur_abc123.pdf",
"purchasedAt": "2025-04-05T16:00:05.000Z"
},
"packingSlipUrl": "https://files.beachdepository.com/slips/ship_in_abc123.pdf"
}
}
{
"data": {
"shipment": {
"id": "jn7shipin123",
"fboAccountId": "m97fbo456",
"organizationId": "k57orgxyz",
"status": "created",
"carrier": "FedEx",
"trackingNumber": "794658123456",
"createdAt": "2025-04-05T16:00:00Z"
},
"packingSlipUrl": "https://files.beachdepository.com/slips/ship_in_abc123.pdf"
}
}