Pulling Orders Data

This tutorial covers the four ways to get order data out of OmniCart, from paginated JSON pulls (best for scheduled syncs) to bulk CSV exports (best for historical backfills).

Prerequisite: an admin token — see Data Access Overview.

1. Paginated orders pull — GET /admin/orders

The workhorse for scheduled syncs into a warehouse or BI pipeline.

curl -G 'https://your-store.omnicart.cc/admin/orders' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'order=created_at' \
  --data-urlencode 'created_at[$gte]=2026-07-01T00:00:00Z' \
  --data-urlencode 'created_at[$lt]=2026-07-02T00:00:00Z' \
  --data-urlencode 'fields=id,display_id,status,email,total,currency_code,created_at,updated_at,sales_channel_id'

Key query parameters:

Param Notes
limit / offset Pagination. Default limit is small (15–20) — set it explicitly.
order Sort field; prefix - for descending (e.g. -created_at). Sort ascending by created_at for stable pagination during syncs.
created_at / updated_at Operator maps: [$gte], [$lte], [$lt], [$gt]. Values are exact instants — send ISO timestamps with explicit Z/offset.
status Order status, single value or array.
sales_channel_id Filter to one or more stores/channels.
customer_id, region_id, q Additional filters / free-text search.
fields Comma-separated field list. Use *items to expand line items, *shipping_address for addresses, fulfillments.*, payment_collections.* for related records.

Response shape:

{
  "orders": [
    {
      "id": "order_01...",
      "display_id": 12345,
      "status": "completed",
      "total": 89.97,
      "created_at": "2026-07-01T14:22:31.000Z",
      "...": "..."
    }
  ],
  "count": 1284,
  "limit": 100,
  "offset": 0
}

count is the total match count — loop offset += limit until you've fetched count rows.

Incremental sync recipe: store the max updated_at you've seen, then each run filter updated_at[$gte]=<last_cursor> and upsert by id. Using updated_at (not created_at) means status changes, refunds, and fulfillment updates flow into your warehouse too.

Remember: total and all money fields are decimal dollars (89.97 = $89.97).

2. Fulfillment & shipping view — GET /admin/fulfillment

A slim, fast list oriented around shipping operations: shipped state, carrier lifecycle, notification-email status. Ideal for ops reporting (e.g. "orders placed > 3 days ago, not yet shipped").

curl -G 'https://your-store.omnicart.cc/admin/fulfillment' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'fulfillment_filter=awaiting' \
  --data-urlencode 'created_at_gte=2026-07-01T00:00:00Z' \
  --data-urlencode 'no_cache=1'

Useful parameters:

Param Notes
fulfillment_filter awaiting, shipped, shipped_no_email, email_sent, email_missed, on_hold, needs_review, quickbox_errors, cancelled, all
created_at_gte / created_at_lte Date window (exact instants)
date_axis Which date the window applies to: placed, shipped, email_sent, or auto
placed_at_*, shipped_at_*, email_sent_* Per-field date ranges (_gte/_lte) that combine freely
has_shipped, email_sent, on_hold, needs_review Tri-state boolean filters (true/false, omit for "any")
sales_channel_id, q, order Channel filter, search (order # or email), sort
no_cache=1 Bypass the server cache (responses are otherwise up to 3 minutes stale; check the X-Cache header)

Always bound fulfillment queries with a date window (created_at_gte/created_at_lte or the per-field ranges). On stores with large order histories, unbounded filtered queries can exceed internal query timeouts and fail — a date window keeps them fast and reliable.

Each row includes display_id, email, total, status, payment_status, is_shipped, shipped_at, shipping-email timestamps, carrier lifecycle fields, and sales_channel — but not line items or addresses. Fetch a single order's full detail with GET /admin/fulfillment/:id. On very large unfiltered queries, count may be an estimate.

3. CSV exports

Fulfillment table CSV — GET /admin/fulfillment/export-csv

Same filters as the list above; returns a CSV (with header row) matching the dashboard table: order #, dates, recipient, email, store, sync status, carrier lifecycle timestamps, total, currency.

curl -G 'https://your-store.omnicart.cc/admin/fulfillment/export-csv' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --data-urlencode 'fulfillment_filter=shipped' \
  --data-urlencode 'created_at_gte=2026-06-01T00:00:00Z' \
  -o shipped-orders.csv

Capped at 50,000 rows. If your filter matches more, the response carries an X-Export-Truncated: true header — narrow the date window and export in chunks.

Bulk order export (async) — POST /admin/orders/export

The intended path for large historical exports. Returns immediately with a transaction id; the CSV is generated in the background and delivered as a notification in the admin dashboard feed with a download URL.

curl -X POST 'https://your-store.omnicart.cc/admin/orders/export?created_at[$gte]=2026-01-01&created_at[$lte]=2026-06-30' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response: 202 Accepted with { "transaction_id": "..." }.

Two things make this endpoint different:

  1. Date filters snap to calendar days in the report timezone (US Eastern by default). created_at[$gte]=2026-01-01 means midnight Eastern on Jan 1, and the upper bound is extended to the end of its calendar day. This is what you want for "monthly report" semantics; it is different from the raw-instant filtering everywhere else. You can pass a timezone parameter (IANA name, e.g. America/Chicago) to change it per-request.
  2. The CSV is not in the HTTP response. Watch the admin notification feed for the file link.

Columns include order IDs, status, date (rendered in the report timezone), customer name/email/ID, shipping address, fulfillment & payment status, subtotal/shipping/discount/tax/total, currency, and a compact items summary.

Tax report — GET /admin/reports/taxes/export

curl -G 'https://your-store.omnicart.cc/admin/reports/taxes/export' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  --data-urlencode 'start_date=2026-04-01T00:00:00Z' \
  --data-urlencode 'end_date=2026-06-30T23:59:59Z' \
  --data-urlencode 'format=json' \
  --data-urlencode 'include_orders=true'

start_date and end_date are required. format is csv (default) or json. JSON returns summaryByState (order count, taxable amount, tax collected, average rate per state) plus totalTaxCollected, and per-line orderDetails when include_orders=true. Add state=TX to scope to one state. Keep windows reasonable (a quarter at a time) — this endpoint scans the full range in one pass.

Gotchas checklist for scheduled jobs