Talk to an Expert
Orders - Grasshopper Labs API
DocsOrders
Orders

Orders

The core of the Grasshopper platform. Orders are the entities you push from your retail/OMS system into the network for last-mile delivery.

Endpoints

GET /api/orders/ List orders Paginated, filterable list of orders in your shipper scope. POST /api/orders/ Create order Push a new order into Grasshopper for fulfillment. GET /api/orders/{order_id}/ Retrieve order Fetch a single order with full details. PATCH /api/orders/{order_id}/ Update order Partial update of customer info, notes, or schedule. POST /api/orders/{order_id}/cancel/ Cancel order Cancel an order before it's loaded for delivery.

The order object

Every endpoint returns or accepts variants of the order object. Top-level fields:

order_id
string Optional
Grasshopper's internal order ID. Returned by the API; not provided on create.
ref_order_number
string Required
Your internal PO or reference number. Used for cross-referencing back to your system.
service_level
string Required
Service level code.
wgrocparocprocthrcurbb2bblnkexpprcl
status
integer Optional
Numeric order status. See Order statuses.
customer
object Required
Consignee details. Includes first_name, last_name, email, phone1, address.
line_items
array Required
Array of items in the order. At least one required.
assets
array Optional
Images and documents attached to the order. Populated after delivery (POD, signatures).
notes
array Optional
Notes attached to the order.
delivery
object Optional
Scheduling state and delivery date.
tracking
array Optional
Order-level tracking events. See Tracking events.
created_at
string (ISO 8601) Optional
Timestamp when the order was created.
updated_at
string (ISO 8601) Optional
Timestamp of the last modification.

Typical lifecycle

  1. POST /api/orders/ — you create the order, status becomes 2 (Pending Pickup) or 1 (Pending Arrival)
  2. Order moves through hub network → status updates to 10 (In transit), then 3 (Received) or 15 (Consolidated)
  3. Customer schedules delivery → delivery.status moves 0 → 1 → 2 → 3
  4. Day of delivery → status 4 (Out for Delivery), then terminal 5 (Delivered) or 20 (Failed)
  5. POD asset attached, ELECTRONIC_POD_SENT webhook fires
← Previous
Changelog