Jump to a documentation page

What this API does

The Orders API lets you list orders from your wholesale portal, with flexible filters and paging. Use it to power reporting tools, dashboard widgets, or to sync orders into other systems.

Format: JSON. Character set: UTF-8. Authentication: API key header or api_key parameter.

Authentication

Include your API key in one of the following ways:

Header: X-API-Key: YOUR_API_KEY
Query parameter: ?api_key=YOUR_API_KEY

Tip: Prefer the header method. Query parameters are supported for convenience.

Quick start

GET /api/orders/?per_page=50&page=1

A successful response contains a meta section with filters and pagination, and a data array of orders.

Filtering options

Status

Return only certain statuses. Separate multiple with commas.

?status=pending,confirmed

Customer or user

?customer_id=123
?user_id=456

Order identifiers

?order_number=SO-100045
?po_number=PO-7788

Search term

Fuzzy search across order number, customer name, customer code, and PO number.

?q=Acme

Totals

?min_total=100.00
?max_total=500.00

Date ranges

Use a generic range on a chosen column, or dedicated placed/updated filters.

Parameter	What it filters	Example
date_from, date_to	Range applied to `filter_on`	`?filter_on=created_at&date_from=2025-01-01&date_to=2025-01-31`
filter_on	`created_at` (default), `updated_at`, or `placed_at`	`?filter_on=updated_at`
placed_from, placed_to	Range on `placed_at` only	`?placed_from=2025-03-01&placed_to=2025-03-31`
updated_since	Changed on or after timestamp	`?updated_since=2025-06-01%2000:00:00`

If you pass dates as YYYY-MM-DD, the API expands them to start or end of day.

Include related data

Enrich each order by including related records. Use a comma-separated list.

items - line items with sku, name, qty, and pricing
shipments - shipments, tracking, and timestamps
status_history - status changes with who and when

?include=items,shipments,status_history

Sorting and pagination

Sort by one or more fields. Prefix with a minus to sort descending.

Sortable field	Meaning	Example
`created_at`	Order created timestamp	`?sort=-created_at`
`updated_at`, `placed_at`	Updated or placed timestamps	`?sort=placed_at,-updated_at`
`grand_total`	Total amount	`?sort=-grand_total`
`order_number`, `status`, `customer_name`	Order number, status, or customer name	`?sort=customer_name`

Pagination uses page and per_page. Default per page is 50. Maximum is 250.

?page=2&per_page=100

Response shape

Example structure with optional sections shown:

{
  "meta": {
    "tenant_id": 123,
    "filters": { ... },
    "pagination": { "page": 1, "per_page": 50, "total": 380, "total_pages": 8 },
    "sort": "created_at",
    "timings_ms": { "total": 12 }
  },
  "data": [
    {
      "id": 1001,
      "order_number": "SO-1001",
      "customer": {
        "id": 55,
        "name": "Acme Wholesale",
        "code": "ACME",
        "email": "buyer@example.com"
      },
      "user_id": 77,
      "currency": "USD",
      "status": "confirmed",
      "po_number": "PO-7788",
      "notes": "Ship complete",
      "totals": {
        "subtotal": 1200.00,
        "discount_total": 50.00,
        "tax_total": 95.00,
        "shipping_total": 30.00,
        "grand_total": 1275.00
      },
      "placed_at": "2025-03-24 10:42:18",
      "created_at": "2025-03-24 10:40:02",
      "updated_at": "2025-03-24 10:42:18",
      "items": [ ... ],
      "shipments": [ ... ],
      "status_history": [ ... ]
    }
  ]
}

Examples you can copy

Recent confirmed orders, newest first:

GET /api/orders/?status=confirmed&sort=-placed_at&page=1&per_page=50

Orders created in January with total between 100 and 500:

GET /api/orders/?filter_on=created_at&date_from=2025-01-01&date_to=2025-01-31&min_total=100&max_total=500

Include items and shipments for a dashboard drill-down:

GET /api/orders/?include=items,shipments&page=1&per_page=25

Updated since a timestamp, sorted by most recently updated:

GET /api/orders/?updated_since=2025-06-01%2000:00:00&sort=-updated_at

Error handling

Errors are returned as JSON with an HTTP status code.

{
  "error": {
    "type": "missing_api_key",
    "message": "api_key is required (use X-API-Key header or api_key param)."
  }
}

Status	When it happens
401 Unauthorized	Missing or invalid API key
400 Bad Request	Invalid parameter formats
422 Unprocessable Entity	Recognized but not acceptable inputs
429 Too Many Requests	Rate limiting, if enforced
500 Internal Server Error	Unexpected server error

Best practices

Use per_page between 50 and 250 and iterate through page.
Sort by a stable field such as -updated_at when syncing.
Cache results where possible and re-fetch using updated_since for deltas.
Request only needed relationships with include=... to keep responses fast.

Glossary

Order: A submitted cart with totals and status.
Placed at: When the buyer finalized the order.
Status: Lifecycle such as pending, confirmed, shipped, completed, canceled.
Shipments: One or more packages attached to an order with tracking details.
Status history: Audit log of status changes over time.

Documentation

Orders API - Admin User Guide