> ## Documentation Index
> Fetch the complete documentation index at: https://agents.concierca.ch/llms.txt
> Use this file to discover all available pages before exploring further.
# Orders
> E-commerce orders with status tracking — Shopify-sourced, ingest-enabled.
## What it is
E-commerce orders with status tracking. One row per order, sourced from your shop system (Shopify in the standard setup — `external_id` is the Shopify Order gid). Orders carry payment state (`financial_status`), shipping state (`fulfillment_status`), totals, and full billing/shipping address blocks. Line-level detail lives in [Order Line Items](/api/data-model/order-line-items), linked via `order_external_id`.
Orders are the raw material for the demand and retention analytics: [Product Demand](/api/data-model/product-demand), [Weekly Sales](/api/data-model/weekly-sales), and [Customer Reorder Due](/api/data-model/customer-reorder-due) are all computed from them. A sale counts when `financial_status` is not refunded/expired/voided, and it counts on `placed_at` — never on the sync date.
## How it gets data
Ingest-enabled — external systems push rows through the [Ingest API](/api/ingest):
```http theme={null}
POST /api/ingest/orders
Authorization: Bearer pk_...
Content-Type: application/json
```
* One JSON record per request. Only registered columns are accepted; unknown fields are dropped.
* **Idempotent upsert** on `(tenant_id, external_id)` — re-sending the same `external_id` updates the row, never duplicates it.
* `tenant_id` / `workspace_id` come from the API key context, never from the body.
* A ready-made **Make.com flow template** for Shopify → orders is downloadable in Settings → Data Sources.
Minimal example payload:
```json theme={null}
{
"external_id": "gid://shopify/Order/5678901234",
"order_name": "#1001",
"total": 249.90,
"currency": "EUR",
"financial_status": "PAID",
"fulfillment_status": "UNFULFILLED",
"customer_external_id": "gid://shopify/Customer/111",
"customer_email": "anna@example.com",
"placed_at": "2026-08-01T10:00:00Z",
"shop_source": "my-shop"
}
```
Demand analytics filter on `financial_status` (refunded/expired/voided orders don't count as sales) and date on `placed_at` — send both. The legacy `status` column is no longer populated by modern Shopify syncs; keep sending fulfillment updates so paid-but-unshipped tracking stays accurate.
## Fields
### Identity & status
| Field | Label | Type | Writable | Description |
| --------------------- | ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `external_id` | Order ID | text | ingest | Source order id (Shopify Order gid) — the upsert key. Required |
| `order_name` | Order Name | text | ingest | Human-readable order number as shown in the shop (e.g. `#1001`) |
| `status` | Status | status | ingest | Legacy combined status. Modern syncs leave it NULL and use `financial_status` / `fulfillment_status` instead |
| `financial_status` | Financial Status | text | ingest | Payment state from the shop: `PAID`, `PENDING`, `PARTIALLY_REFUNDED`, `REFUNDED`, `EXPIRED`, `VOIDED`. The sales filter for all demand analytics |
| `fulfillment_status` | Fulfillment Status | text | ingest | Shipping state: `UNFULFILLED`, `ON_HOLD`, `PARTIALLY_FULFILLED`, `FULFILLED`. Drives the paid-but-unshipped (`quantity_committed`) calculation |
| `confirmed` | Confirmed | boolean | ingest | Whether the shop has confirmed the order |
| `fully_paid` | Fully Paid | boolean | ingest | Whether the order is fully paid, as reported by the shop |
| `confirmation_number` | Confirmation Number | text | ingest | Shop confirmation code shown to the customer |
| `po_number` | Po Number | text | ingest | Buyer's purchase-order number, when given at checkout (B2B) |
| `legacy_resource_id` | Legacy Resource Id | text | ingest | Shopify numeric order id (`legacyResourceId`) — useful for joining with exports that don't use gids |
| `status_page_url` | Status Page Url | text | ingest | Link to the customer-facing order-status page |
| `updated_at` | Updated At | text | ingest | Last update time reported by the source system |
### Money & customer
| Field | Label | Type | Writable | Description |
| ---------------------- | -------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `total` | Total | currency | ingest | Order total in `currency`. Required |
| `currency` | Currency | text | ingest | ISO currency code of the order |
| `customer_external_id` | Customer | text | ingest | Source customer id — joins to `customers.external_id` and powers the reorder analytics |
| `customer_email` | Customer Email | text | ingest | Customer email at order time (fallback join key when no customer id is available) |
| `placed_at` | Placed At | datetime | ingest | When the order was placed. The date every sales calculation uses. Required |
| `note` | Note | text | ingest | Free-text order note from the shop |
| `tags` | Tags | json | ingest | Order tags from the source (array) |
| `shop_source` | Shop Source | text | ingest | Which Shopify store / shop this order originated from — kept for per-store drill-down when several shops feed one workspace |
| `metadata` | Metadata | json | ingest | Raw source fields that don't map to a column — kept so nothing from the source payload is lost |
### Shipping address
| Field | Label | Type | Writable | Description |
| ------------------------ | ---------------------- | ---- | -------- | ------------------------------------------------- |
| `shipping_name` | Shipping Name | text | ingest | Ship-to full name |
| `shipping_first_name` | Shipping First Name | text | ingest | Ship-to first name |
| `shipping_last_name` | Shipping Last Name | text | ingest | Ship-to last name |
| `shipping_phone` | Shipping Phone | text | ingest | Ship-to phone number |
| `shipping_company` | Shipping Company | text | ingest | Ship-to company, when B2B |
| `shipping_address1` | Shipping Address1 | text | ingest | Ship-to street address, line 1 |
| `shipping_address2` | Shipping Address2 | text | ingest | Ship-to street address, line 2 (apartment, suite) |
| `shipping_city` | Shipping City | text | ingest | Ship-to city |
| `shipping_province` | Shipping Province | text | ingest | Ship-to state/province name |
| `shipping_province_code` | Shipping Province Code | text | ingest | Ship-to state/province ISO code |
| `shipping_zip` | Shipping Zip | text | ingest | Ship-to postal code |
| `shipping_country` | Shipping Country | text | ingest | Ship-to country name |
| `shipping_country_code` | Shipping Country Code | text | ingest | Ship-to country ISO code |
| `shipping_carrier` | Shipping Carrier | text | ingest | Carrier chosen for the shipment |
### Billing address
| Field | Label | Type | Writable | Description |
| -------------------------- | ------------------------ | ------- | -------- | --------------------------------------------------------- |
| `billing_matches_shipping` | Billing Matches Shipping | boolean | ingest | True when the billing address equals the shipping address |
| `billing_name` | Billing Name | text | ingest | Bill-to full name |
| `billing_first_name` | Billing First Name | text | ingest | Bill-to first name |
| `billing_last_name` | Billing Last Name | text | ingest | Bill-to last name |
| `billing_phone` | Billing Phone | text | ingest | Bill-to phone number |
| `billing_company` | Billing Company | text | ingest | Bill-to company, when B2B |
| `billing_address1` | Billing Address1 | text | ingest | Bill-to street address, line 1 |
| `billing_address2` | Billing Address2 | text | ingest | Bill-to street address, line 2 |
| `billing_city` | Billing City | text | ingest | Bill-to city |
| `billing_province` | Billing Province | text | ingest | Bill-to state/province name |
| `billing_province_code` | Billing Province Code | text | ingest | Bill-to state/province ISO code |
| `billing_zip` | Billing Zip | text | ingest | Bill-to postal code |
| `billing_country` | Billing Country | text | ingest | Bill-to country name |
| `billing_country_code` | Billing Country Code | text | ingest | Bill-to country ISO code |
"ingest" = populated through the ingest endpoint; read-only in the app and over MCP row writes. `metadata` is accepted on ingest but not surfaced as a default table column.
Like every workspace table, orders also carry the system columns `id` (internal row id), `tenant_id`, `workspace_id` (tenant isolation — stamped from the API key), and `created_at` (row creation). Never send them; they are managed automatically.
## Query it
```json theme={null}
{
"method": "tools/call",
"params": {
"name": "data_query",
"arguments": {
"view_slug": "orders",
"filters": { "financial_status": "PAID", "fulfillment_status": "UNFULFILLED" },
"select_fields": ["order_name", "total", "currency", "customer_email", "placed_at"],
"sort_by": "placed_at",
"limit": 50
}
}
}
```