Fulfilment Orders

Last updated October 19, 2026

Base URL

All examples assume BASE_URL=https://api.omnishelf.com and OMNI_KEY=omni_sk_YOUR_KEY.

---

GET /v1/fulfilment-orders

List the orders that are actionable for you, newest date last, with cursor pagination.

Query parameters

Parameter	Type	Default	Notes
status	Comma-separated list	awaiting_shipment,processing	Allowed: awaiting_shipment, processing, on_hold, cancelled. Any other value returns a validation_error.
order_date_from	YYYY-MM-DD	—	Inclusive lower bound on order_date. Must be a real calendar date.
order_date_to	YYYY-MM-DD	—	Inclusive upper bound on order_date. Must not be earlier than order_date_from.
warehouse	String	—	Warehouse code. Matches orders with at least one line item routed to that warehouse. An unknown code returns an empty list, not an error.
limit	Integer	50	Maximum 200: a larger value is treated as 200. A value below 1 or not a whole number falls back to 50.
cursor	Opaque string	—	next_cursor from the previous page. An unparseable cursor is a validation_error.

Unknown query parameters are rejected

Only the six parameters above are accepted. Any other parameter, including a misspelt one, returns 400 validation_error with a hint instead of being silently ignored:

{
  "error": "validation_error",
  "message": "Unknown query parameter \"order_date_start\" (did you mean \"order_date_from\"?). Supported parameters: status, order_date_from, order_date_to, warehouse, limit, cursor."
}

Before this change, unknown parameters were silently ignored, so a misspelt filter had no effect. If your integration sends extra parameters, remove them.

Request

curl -s "$BASE_URL/v1/fulfilment-orders?status=processing&order_date_from=2026-07-01&limit=50" \
  -H "Authorization: Bearer $OMNI_KEY"

Response — 200

{
  "data": [
    {
      "order_id": "OMN-KONW-00042",
      "status": "processing",
      "order_date": "2026-07-28",
      "created_at": "2026-07-28T14:22:00Z",
      "updated_at": "2026-07-29T09:10:00Z",
      "parcel_count": 3,
      "warehouse": {
        "code": "TETRIS",
        "name": "Tetris Prep"
      },
      "shipping_address": {
        "name": "Jordan Ellis",
        "line1": "1420 Sycamore Ave",
        "line2": null,
        "city": "Baltimore",
        "state": "MD",
        "postal_code": "21201",
        "country": "US"
      },
      "items": [
        { "sku": "YT-FL-RV-A-028-YE-1", "product_name": "31000 Lumen LED Work Lights", "quantity": 5 },
        { "sku": "YT-FL-RV-A-031-BK-2", "product_name": "Heavy Duty Tripod Stand", "quantity": 2 }
      ],
      "shipments": [
        {
          "shipment_id": "OMN-KONW-00042-1",
          "sequence": 1,
          "carrier": "ups",
          "parcels": [
            {
              "parcel_id": "OMN-KONW-00042-1-1",
              "parcel_number": 1,
              "tracking_number": "1Z0K49Y40312446341",
              "carrier": "ups",
              "has_label": true,
              "weight": 11.0,
              "weight_unit": "lb",
              "dimensions": { "length": 17.0, "width": 13.0, "height": 5.0, "unit": "in" }
            }
          ]
        }
      ]
    }
  ],
  "pagination": {
    "next_cursor": "eyJkIjoiMjAyNi0wNy0yOCIsIm8iOiJPTU4tS09OVy0wMDA0MiJ9",
    "has_more": true
  }
}

Errors

• 400 validation_error — any of:
  • an unknown query parameter
  • an unsupported status value
  • a date that is not YYYY-MM-DD or is not a real calendar date (e.g. 2026-02-30)
  • order_date_from later than order_date_to
  • an invalid cursor
• 200 with empty data array — no matching orders, including an unknown warehouse code. Not an error.

Note on warehouse

warehouse reflects the warehouse of the first line item that has been routed. If an order draws stock from more than one, the object gains "mixed": true and you should look at the shipments to see how it was split.

If the order has not been routed to a warehouse yet, warehouse falls back to your main warehouse instead of being empty. The object always has a code and name, but on an unrouted order it shows where the order is expected to ship from, not a routing decision. It is null only if you have no active warehouse, or several.

Note on items

items[].sku is your own SKU, the same one GET /v1/inventory and the seller portal show. A line not yet mapped to one of your products keeps the SKU it arrived with. product_name carries no marketplace catalogue identifiers. Webhook payloads use the same values.

---

GET /v1/fulfilment-orders/{order_id}

Fetch one fulfilment order by its Omnishelf order ID.

Path parameters

Parameter	Example	Notes
order_id	OMN-KONW-00042	Omnishelf order ID.

Request

curl -s "$BASE_URL/v1/fulfilment-orders/OMN-KONW-00042" \
  -H "Authorization: Bearer $OMNI_KEY"

Response — 200

Identical object shape to a single entry in the list response, wrapped in data with no pagination.

{
  "data": {
    "order_id": "OMN-KONW-00042",
    "status": "processing",
    "order_date": "2026-07-28",
    "created_at": "2026-07-28T14:22:00Z",
    "updated_at": "2026-07-29T09:10:00Z",
    "parcel_count": 3,
    "warehouse": { "code": "TETRIS", "name": "Tetris Prep" },
    "shipping_address": {
      "name": "Jordan Ellis",
      "line1": "1420 Sycamore Ave",
      "line2": null,
      "city": "Baltimore",
      "state": "MD",
      "postal_code": "21201",
      "country": "US"
    },
    "items": [
      { "sku": "YT-FL-RV-A-028-YE-1", "product_name": "31000 Lumen LED Work Lights", "quantity": 5 }
    ],
    "shipments": [
      {
        "shipment_id": "OMN-KONW-00042-1",
        "sequence": 1,
        "carrier": "ups",
        "parcels": [
          {
            "parcel_id": "OMN-KONW-00042-1-1",
            "parcel_number": 1,
            "tracking_number": "1Z0K49Y40312446341",
            "carrier": "ups",
            "has_label": true,
            "weight": 11.0,
            "weight_unit": "lb",
            "dimensions": { "length": 17.0, "width": 13.0, "height": 5.0, "unit": "in" }
          }
        ]
      }
    ]
  }
}

Errors

• 404 not_found — the order does not exist, or belongs to another seller. The two are deliberately indistinguishable.