Talk to an Expert
List orders - Grasshopper Labs API
DocsOrdersList orders
Orders

List orders

Paginated, filterable list of orders in your shipper scope.

GET /api/orders/

Query parameters

status
integer Optional
Filter by order status ID. See Order statuses.
service_level
string Optional
Filter by service level code (e.g. wg, thr).
created_after
string (ISO 8601) Optional
Return orders created at or after this timestamp.
created_before
string (ISO 8601) Optional
Return orders created before this timestamp.
ref_order_number
string Optional
Filter by your PO / reference number. Supports partial match.
page
integer Optional
Page number (1-indexed). Defaults to 1.
per_page
integer Optional
Results per page. Min 1, max 100. Defaults to 25.

Example request

curl -G https://{licensee-url}/api/orders/ \
  -H "Authorization: Bearer $TOKEN" \
  -d "status=4" \
  -d "per_page=50"
const params = new URLSearchParams({ status: 4, per_page: 50 });
const res = await fetch(`https://{licensee-url}/api/orders/?${params}`, {
  headers: { Authorization: `Bearer ${token}` }
});
const data = await res.json();
import requests

res = requests.get(
    'https://{licensee-url}/api/orders/',
    headers={'Authorization': f'Bearer {token}'},
    params={'status': 4, 'per_page': 50}
)
orders = res.json()['data']
{
  "data": [
    {
      "order_id": "22200041771",
      "ref_order_number": "PO-12345",
      "status": 4,
      "service_level": "wg",
      "created_at": "2026-05-10T14:38:43.969Z"
      /* ... abbreviated ... */
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 142,
    "total_pages": 3
  }
}
Try it out
Response will appear here

Errors

StatusCause
400Invalid query parameter format (e.g. non-numeric status)
401Missing or invalid token
← Previous
Orders overview