Inbound

Endpoints for managing inbound orders — the items being shipped to your warehouse.

POST/api/v1/inbound

Create an inbound order

Create a new inbound order. Data is sent as multipart/form-data to support file uploads for shipping labels.

You can also bulk-upload orders by setting bulk=true and attaching a CSV file.

Required attributes

Name
date
Type
string
Description
Order date.
Name
retailer
Type
string
Description
Where the item was purchased from.
Name
order_number
Type
string
Description
Your order reference number.
Name
item_name
Type
string
Description
Name of the item.
Name
color
Type
string
Description
Item color or variant.
Name
brand_sku
Type
string
Description
Your internal SKU.
Name
quantity
Type
integer
Description
Number of units.
Name
asin
Type
string
Description
Amazon ASIN. Required for FBA and FBM fulfillment types.
Name
unit_cost
Type
number
Description
Cost per unit.
Name
list_price
Type
number
Description
Listing price per unit.
Name
fulfillment_type
Type
string
Description
Fulfillment type: fba, fbm, wfs, two-step, or shopify.

Optional attributes

Name
size
Type
string
Description
Item size or variant.
Name
amazon_sku
Type
string
Description
Amazon MSKU.
Name
client_notes
Type
string
Description
Notes for the warehouse.
Name
tracking_numbers
Type
array
Description
Tracking numbers for the inbound shipment.
Name
sold_as
Type
string
Description
How the item is sold: individual or bundle.
Name
units_per_pack
Type
string
Description
Number of units per pack. Required if sold_as is bundle.
Name
upc
Type
string
Description
UPC barcode.
Name
bundle_items
Type
array
Description
Array of bundle items if sold_as is bundle. Each item: { quantity, item_name, color, ... }.
Name
shipping_label_files
Type
file(s)
Description
Shipping label files. Used for two-step fulfillment.

Request

POST

/api/v1/inbound

curl https://api.example.com/api/v1/inbound \
  -H "Authorization: ApiKey {your-api-key}" \
  -H "X-Warehouse-Id: {warehouse_id}" \
  -F "date=2025-03-25" \
  -F "retailer=Amazon" \
  -F "order_number=ORD-001" \
  -F "item_name=Widget A" \
  -F "color=Blue" \
  -F "brand_sku=WA-BLU-M" \
  -F "quantity=24" \
  -F "asin=B08N5WRWNW" \
  -F "unit_cost=12.50" \
  -F "list_price=24.99" \
  -F "fulfillment_type=fba"

Response

{
  "status": "success",
  "message": "Created order.",
  "data": {
    "order_id": "64c65048-b335-4921-b09d-68d4142d5655"
  }
}

Bulk Upload

POST

/api/v1/inbound

curl https://api.example.com/api/v1/inbound \
  -H "Authorization: ApiKey {your-api-key}" \
  -H "X-Warehouse-Id: {warehouse_id}" \
  -F "bulk=true" \
  -F "file=@orders.csv"

GET/api/v1/inbound

List inbound orders

Retrieve a paginated list of your inbound orders.

Query parameters

Name
offset
Type
integer
Description
Pagination offset. Defaults to 0.
Name
limit
Type
integer
Description
Maximum number of records to return. Defaults to 200. Pass -1 for all records.
Name
sort_key
Type
string
Description
Field to sort by. Defaults to created_at.
Name
sort_order
Type
string
Description
Sort direction: asc or desc. Defaults to desc.
Name
fulfillment_types
Type
array
Description
Filter by fulfillment type: fba, fbm, wfs, two-step.
Name
lang
Type
string
Description
Language for translations. Defaults to en.

Request

GET

/api/v1/inbound

curl -G https://api.example.com/api/v1/inbound \
  -H "Authorization: ApiKey {your-api-key}" \
  -H "X-Warehouse-Id: {warehouse_id}" \
  -d limit=50 \
  -d offset=0 \
  -d sort_key=created_at \
  -d sort_order=desc

Response

{
  "status": "success",
  "message": "Fetched orders.",
  "data": {
    "orders": [
      {
        "order_id": "64c65048-b335-4921-b09d-68d4142d5655",
        "date": "03/25/2025",
        "retailer": "Amazon",
        "order_number": "ORD-001",
        "item_name": "Widget A",
        "color": "Blue",
        "brand_sku": "WA-BLU-M",
        "size": "Medium",
        "quantity": 24,
        "asin": "B08N5WRWNW",
        "amazon_sku": "WA-BLU-M-FBA",
        "unit_cost": 12.50,
        "list_price": 24.99,
        "client_notes": null,
        "fulfillment_type": "fba",
        "sold_as": "individual",
        "units_per_pack": 1,
        "upc": null,
        "tracking_numbers": ["1Z999AA10123456784"],
        "status": "inbound",
        "created_at": "2025-03-25T21:05:40Z"
      }
    ],
    "results": {
      "total": 150,
      "limit": 50,
      "offset": 0
    }
  }
}

PUT/api/v1/inbound/:order_id

Update an inbound order

Update an existing inbound order. Send only the fields you want to change — all fields are optional.

Path parameters

Name
order_id
Type
string (uuid)
Description
The ID of the inbound order to update.

Request body

Name
date
Type
string
Description
Order date.
Name
retailer
Type
string
Description
Retailer name.
Name
orderNumber
Type
string
Description
Order reference number.
Name
itemName
Type
string
Description
Item name.
Name
color
Type
string
Description
Item color or variant.
Name
brandSKU
Type
string
Description
Internal SKU.
Name
size
Type
string
Description
Item size.
Name
quantity
Type
integer
Description
Number of units. Must be divisible by units_per_pack for bundles.
Name
asin
Type
string
Description
Amazon ASIN.
Name
amazonSKU
Type
string
Description
Amazon MSKU. Must start with PFL for FBM orders, or leave empty to auto-generate.
Name
cogs
Type
number
Description
Unit cost.
Name
listPrice
Type
number
Description
List price per unit. Required and must be non-zero for FBM orders.
Name
notes
Type
string
Description
Client notes.
Name
fulfilledBy
Type
string
Description
Fulfillment type: fba, fbm, wfs, two-step, shopify, manual. Cannot be changed once the order has been shipped.
Name
trackingNumbers
Type
array
Description
Replaces all existing tracking numbers. Carrier is auto-detected.
Name
sold_as
Type
string
Description
How the item is sold: individual, multi-pack, or bundle.
Name
units_per_pack
Type
integer
Description
Units per pack. Required if sold_as is not individual.

Validation rules

Cannot change fulfilledBy when order status is outbound (already shipped)
FBM orders: amazonSKU must start with PFL (or be empty for auto-generation); listPrice must be non-zero; Seller Central must be linked
If sold_as is not individual: units_per_pack must be a positive integer and quantity must be divisible by it
Bundle orders: changing quantity syncs all child bundle item quantities

Request

PUT

/api/v1/inbound/:order_id

curl -X PUT https://api.example.com/api/v1/inbound/64c65048-b335-4921-b09d-68d4142d5655 \
  -H "Authorization: ApiKey {your-api-key}" \
  -H "X-Warehouse-Id: {warehouse_id}" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 30, "notes": "Updated quantity"}'

Response

{
  "status": "success",
  "message": "Updated inbound order.",
  "data": null
}

Error (400)

{
  "status": "failed",
  "message": "An error occurred while processing your request.",
  "errors": [
    "Your amazon SKU must start with PFL for FBM orders or leave empty to auto generate it.",
    "List price must be filled out for FBM orders.",
    "Units per pack must be divisible by the total quantity ordered.",
    "Cannot change fulfilled by when order has been shipped out."
  ]
}

PUT/api/v1/inbound/bulk

Bulk update inbound orders

Apply the same field updates and/or tracking numbers to many inbound orders in one call.

Unlike the single-order PUT /api/v1/inbound/:order_id endpoint above, the bulk endpoint expects snake_case field names (matching the underlying database columns).

Required attributes

Name
order_ids
Type
array
Description
Array of inbound order UUIDs to update. The same field changes are applied to every order in the list.

Optional attributes

Send only the fields you want to change — every field below is optional.

Name
tracking_numbers
Type
array
Description
Tracking numbers to append to each order in order_ids. Carriers are auto-detected. If this is the only field provided, the call will still attach the trackings to every order.
Name
fulfillment_type
Type
string
Description
Fulfillment type: fba, fbm, wfs, two-step, or shopify.
Name
retailer
Type
string
Description
Where the item was purchased from.
Name
order_number
Type
string
Description
Order reference number.
Name
item_name
Type
string
Description
Name of the item.
Name
color
Type
string
Description
Item color or variant.
Name
brand_sku
Type
string
Description
Your internal SKU.
Name
size
Type
string
Description
Item size or variant.
Name
quantity
Type
integer
Description
Number of units.
Name
asin
Type
string
Description
Amazon ASIN. Whitespace is trimmed automatically.
Name
amazon_sku
Type
string
Description
Amazon MSKU. Whitespace is trimmed automatically.
Name
unit_cost
Type
number
Description
Cost per unit.
Name
list_price
Type
number
Description
List price per unit.
Name
client_notes
Type
string
Description
Notes for the warehouse.

Behavior & validation rules

The same field set is applied to every order in order_ids in a single transaction.
amazon_sku and asin are trimmed of leading/trailing whitespace.
unit_cost and list_price are normalized server-side.
fulfillment_type cannot be changed on orders that are already partially_received or fully_received.
Switching an order to fbm requires (a) a linked Amazon Seller Central account and (b) a completed FBM setup; otherwise the call fails with a descriptive error.
Updating quantity may auto-transition unit_status to fully_received and status to outbound, inventory, or inbound depending on the order's quantity_received and quantity_remaining.
For bundle parents, changing quantity propagates the new quantity to all child bundle items.
Changes to fulfillment_type or amazon_sku enqueue an inventory recompute event for the old and/or new (sku, fulfillment_type) pair.

Request

PUT

/api/v1/inbound/bulk

curl -X PUT https://api.example.com/api/v1/inbound/bulk \
  -H "Authorization: ApiKey {your-api-key}" \
  -H "X-Warehouse-Id: {warehouse_id}" \
  -H "Content-Type: application/json" \
  -d '{
        "order_ids": [
          "64c65048-b335-4921-b09d-68d4142d5655",
          "7a9c12f0-2e91-4d8a-9f1c-1b3d4e5f6789"
        ],
        "fulfillment_type": "fba",
        "client_notes": "Reassigned to FBA batch",
        "tracking_numbers": ["1Z999AA10123456784"]
      }'

Response

{
  "status": "success",
  "message": "Updated inbound orders.",
  "data": null
}

Error (400)

{
  "status": "failed",
  "message": "An error occurred while processing your request.",
  "errors": [
    "Cannot change fulfilled by when order has been received.",
    "You must link your seller central account in settings before switching to FBM.",
    "You must complete your FBM setup in settings before switching to FBM."
  ]
}