# 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](/tutorials/northbeam) and [Looker / Looker Studio](/tutorials/looker).

## What data is available

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

## 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):

```bash
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**):

```bash
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

- `GET /admin/metrics` results may be up to ~5 minutes stale (server-side cache).
- `GET /admin/fulfillment` is cached for up to 3 minutes (longer for heavy unfiltered views). Add `no_cache=1` when your job needs guaranteed-fresh data, and check the `X-Cache` response header (`HIT` / `STALE` / `MISS`).

## Choosing your integration path

- **Ad-platform attribution (Northbeam):** feed order-level purchase data on a schedule → [Northbeam Integration](/tutorials/northbeam)
- **Dashboards & exploration (Looker, Looker Studio):** land orders data in a warehouse or spreadsheet on a schedule, point the BI tool at it → [Looker & Looker Studio](/tutorials/looker)
- **Custom reporting:** pull raw orders ([Pulling Orders Data](/tutorials/orders-data)) for full flexibility, or let OmniCart compute KPIs for you ([Metrics & Reports API](/tutorials/metrics-data))