Data Access Overview

This section is a practical guide to pulling OmniCart data into reporting and BI tools — scheduled data pulls, CSV exports, computed metrics, and step-by-step integrations for Northbeam and Looker / Looker Studio.

What data is available

Data Best endpoint Format Guide
Orders (raw, paginated) GET /admin/orders JSON Pulling Orders Data
Fulfillment & shipping status GET /admin/fulfillment JSON Pulling Orders Data
Orders (bulk historical) POST /admin/orders/export CSV (async) Pulling Orders Data
Fulfillment table export GET /admin/fulfillment/export-csv CSV Pulling Orders Data
Tax report GET /admin/reports/taxes/export CSV or JSON Pulling Orders Data
Computed KPIs (revenue, AOV, orders, refunds…) GET /admin/metrics, POST /admin/metrics/batch JSON Metrics & Reports API

Setting up API access

All data endpoints live under /admin/* and require admin authentication. You have two options:

Option A — Secret API key (recommended for scheduled jobs)

Create a secret API key in the admin dashboard under Settings → API Key Management (keys start with sk_). Keys don't expire on a timer, aren't tied to a person's password, and can be revoked individually — exactly what you want for a BI pipeline. Use it as the username in HTTP Basic auth (empty password):

curl -X GET 'https://your-store.omnicart.cc/admin/orders?limit=100' \
  -u "sk_YOUR_SECRET_KEY:"

Most admin endpoints accept secret keys; if a specific route returns 401 with a valid key, use Option B for that call.

Option B — Admin JWT (email/password login)

For a dedicated service user (create one under Settings → Users):

curl -X POST 'https://your-store.omnicart.cc/auth/user/emailpass' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "reporting-bot@yourcompany.com",
    "password": "your_password"
  }'

Response: { "token": "eyJ..." } — send it as Authorization: Bearer YOUR_TOKEN on every request.

JWT tokens expire after 7 days by default (deployment-configurable). Don't hard-code the lifetime: re-authenticate whenever you receive a 401.

Conventions every data consumer must know

1. Money is decimal dollars — never cents

All monetary values across every endpoint are decimals: 19.99 means $19.99. Do not divide by 100. If your BI tool or destination expects cents, multiply by 100 on your side.

2. Date filters: timezone semantics differ by endpoint

Endpoint How date filters are interpreted
GET /admin/orders Exact instants, as sent (use ISO timestamps with explicit offsets, e.g. 2026-07-01T00:00:00Z)
GET /admin/fulfillment (+ CSV export) Exact instants, as sent
GET /admin/reports/taxes/export Exact instants, as sent
POST /admin/orders/export Snapped to calendar days in the report timezone (US Eastern by default) — created_at.$gte becomes start-of-day, the upper bound becomes an exclusive start-of-next-day

Recommendation: always send full ISO-8601 timestamps with an explicit Z or offset. Bare dates like 2026-07-01 are interpreted differently per endpoint and are the most common source of off-by-one-day reporting discrepancies.

3. Rate limits (metrics endpoints)

The metrics endpoints define per-minute rate limits that may or may not be enforced in your deployment — treat them as the budget to design for:

Endpoint Limit (when enforced)
GET /admin/metrics 60 requests/minute per user
POST /admin/metrics 10 requests/minute per user
POST /admin/metrics/batch 5 requests/minute per user

Limits are keyed per authenticated user (all jobs sharing one credential share one bucket). If you receive a 429, it includes a Retry-After header — honor it with backoff. Separately, POST /admin/metrics/batch always enforces a hard maximum of 50 requests per batch regardless of rate limiting. Order endpoints have no special rate limits, but be a good citizen: page sequentially, don't hammer in parallel.

4. Caching and freshness

Choosing your integration path