Fulfillment Orders

A fulfillment order represents a group of items from an order that should be fulfilled from a specific location. When an order is created, a fulfillment order is auto-generated and assigned to the store’s default location. Each fulfillment order tracks which items need shipping and how many have been shipped so far.

Fulfillment orders sit between orders and fulfillments — the order says what the customer bought, the fulfillment order says where it ships from, and the fulfillment says that it shipped (with tracking).

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/orders/{id}/fulfillment-orders	Publishable	List fulfillment orders for an order

Fulfillment orders are also available as an expand on the order endpoint: GET /v1/orders/{id}?expand=fulfillment_orders.

---

List fulfillment orders

GET /v1/orders/{id}/fulfillment-orders

Returns all fulfillment orders for the given order, including their items and any fulfillments (shipments) created against them.

Path parameters

Parameter	Type	Description
id	string	Order ID (prefix: ord_)

Request

curl "https://api.hydrajs.dev/v1/orders/ord_abc123def456ghi789/fulfillment-orders" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "fo_abc123def456ghi789",
			"order_id": "ord_abc123def456ghi789",
			"assigned_location_id": "loc_xyz789abc456def123",
			"assigned_location": {
				"name": "Main Warehouse",
				"address_line1": "123 High St",
				"address_line2": null,
				"city": "Birmingham",
				"state": "West Midlands",
				"postal_code": "B1 1AA",
				"country": "GB"
			},
			"status": "in_progress",
			"delivery_method": "shipping",
			"metadata": null,
			"items": [
				{
					"id": "foi_abc123def456ghi789",
					"order_line_item_id": "li_abc123def456ghi789",
					"quantity": 3,
					"fulfilled_quantity": 2,
					"created_at": "2026-08-30T12:00:00.000Z",
					"updated_at": "2026-08-30T14:00:00.000Z"
				}
			],
			"fulfillments": [
				{
					"id": "ful_abc123def456ghi789",
					"fulfillment_order_id": "fo_abc123def456ghi789",
					"status": "shipped",
					"tracking_number": "1Z999AA10123456784",
					"tracking_url": "https://www.ups.com/track?tracknum=1Z999AA10123456784",
					"carrier": "UPS",
					"shipped_at": "2026-08-30T14:00:00.000Z",
					"delivered_at": null,
					"cancelled_at": null,
					"notes": "Shipped via ground",
					"metadata": null,
					"items": [
						{
							"id": "fi_abc123def456ghi789",
							"fulfillment_order_item_id": "foi_abc123def456ghi789",
							"quantity": 2,
							"created_at": "2026-08-30T14:00:00.000Z",
							"updated_at": "2026-08-30T14:00:00.000Z"
						}
					],
					"created_at": "2026-08-30T14:00:00.000Z",
					"updated_at": "2026-08-30T14:00:00.000Z"
				}
			],
			"created_at": "2026-08-30T12:00:00.000Z",
			"updated_at": "2026-08-30T14:00:00.000Z"
		}
	]
}

---

Webhooks

Event	Trigger
fulfillment_order.created	A fulfillment order is auto-created when an order is placed

See Webhooks for subscription setup.

---

Fulfillment order statuses

Status	Description
open	Created, no fulfillments yet
in_progress	At least one fulfillment created but items remain unfulfilled
closed	All items fully fulfilled
cancelled	Fulfillment order cancelled

open ──> in_progress ──> closed
  │          │
  └──> cancelled <──┘

---

The fulfillment order object

Field	Type	Description
id	string	Unique ID (prefix: fo_)
order_id	string	Parent order ID
assigned_location_id	string	Location responsible for fulfilling these items
assigned_location	object | null	Snapshot of location name and address at assignment time
status	string	open, in_progress, closed, cancelled
delivery_method	string	shipping, pickup, local_delivery, none
metadata	object | null	Arbitrary merchant data
items	array	Fulfillment order items (see below)
fulfillments	array	Fulfillments created against this FO (see Fulfillments)
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Fulfillment order item object

Field	Type	Description
id	string	Unique ID (prefix: foi_)
order_line_item_id	string	The original order line item being fulfilled
quantity	integer	Total quantity to fulfill from this location
fulfilled_quantity	integer	Quantity already shipped via fulfillments
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp

Location snapshot object

Field	Type	Description
name	string	Location name at assignment time
address_line1	string | null	Street address
address_line2	string | null	Apartment, suite, etc.
city	string | null	City
state	string | null	State or province
postal_code	string | null	Postal or ZIP code
country	string | null	ISO 3166-1 alpha-2 country code