Build a single-page Orders Manager application powered by the DataDoe REST API. Use when the user asks to create, scaffold, or build an orders manager, orders dashboard, orders table, or order management app using DataDoe.
ReportingRead-onlyAppAPI
Read-only — this skill only reads your data and never changes your Amazon account.
Low-level agent (Cursor, Claude Code, Codex, Aider, etc.): follow the Default Tech Stack below.
High-level vibe coding assistant (Lovable, Base44, Bolt, v0, etc.): ignore the tech stack section entirely; use whatever the platform provides. Follow only the App Features, DataDoe API Integration, and Implementation Rules sections.
App Features
1. Seller/Vendor Picker
On load, fetch connected sellers and vendors from the API.
Show a dropdown to select one. Orders cannot be loaded without a selection.
Only sellers with sellerCentralConnection !== null are valid (Order Line Items source is SELLER_CENTRAL).
2. Orders Table
Display orders in a table with expandable nested rows for line items.
Parent row: amazon_order_id, date, amazon_order_status, fulfillment_channel, sales_channel, total item count, total price.
Child rows (expanded): sku, child_asin, product_name, quantity, item_price_value, item_price_currency, item_status — keyed by amazon_order_item_id (sku can repeat within an order).
Client-side pagination with configurable page size (10/25/50).
3. Filters
Date range: date-from / date-to inputs. Default: last 30 days.
Order status: multi-select checkboxes. Values documented by the DataDoe scheme: Pending, Unshipped, Shipped, Canceled. Some marketplaces return Shipped / Unshipped with a marketplace-specific prefix (Shipped* / Unshipped*), so filter those two with beginsWith (never =); Pending and Canceled can use =.
Applying filters triggers a new export.
4. Order Tagging (Local)
Tags are NOT part of the DataDoe API — they are stored in localStorage.
Each order (amazon_order_id) can have zero or more text tags.
UI: inline tag chips with "add tag" button + text input.
Prefix all localStorage keys with datadoe-orders-manager:: for collision safety.
Show a spinner/skeleton during export creation and polling.
Show user-friendly error messages for API failures (network errors, 429 rate limits, 4xx/5xx).
On 429: auto-retry after Retry-After header value.
DataDoe API Integration
Auth & Config
The app always targets the production DataDoe API at https://api.datadoe.com. During local development, Vite proxies /api requests to this domain to avoid CORS. There is no staging/production distinction — always use the same API target.
.env file structure (create .env.example with the placeholders below):
bash
1# Vite proxies /api → https://api.datadoe.com (CORS bypass for local dev)2VITE_API_BASE_URL=/api
3VITE_PROXY_TARGET=https://api.datadoe.com
4VITE_DATADOE_API_KEY=<your-api-key>
VITE_API_BASE_URLmust always be /api — the browser app never calls api.datadoe.com directly.
VITE_PROXY_TARGETmust always be https://api.datadoe.com — this is the Vite proxy upstream.
VITE_DATADOE_API_KEY — the API key obtained from the DataDoe dashboard.
Header selection logic (mutually exclusive — never send both):
If VITE_DATADOE_API_KEY is set → attach datadoe-api-key header.
Else if VITE_DATADOE_ORGANIZATION_ID is set → attach datadoe-organization-id header.
Always attach Content-Type: application/json and Accept: application/json.
Rate limit: 2 req/s per org. On 429, read Retry-After header, wait, retry.
Anti-Rate-Limit Guardrails (Mandatory)
Global client-side pacing: cap all DataDoe requests to max 1 request every 600ms (<= ~1.67 req/s), leaving headroom under 2 req/s.
Single in-flight flow per seller: never run multiple export flows in parallel for the same seller.
No parallel polling: only one active poll loop per export; cancel/replace stale loops before starting new ones.
Debounce filter-triggered exports: wait 400-800ms after filter changes before creating a new export.
Serialize bursty steps: when chaining create → poll → raw download, avoid extra background fetches in parallel.
Respect Retry-After exactly on 429, then add incremental delay for subsequent retries.
If these constraints conflict with UI responsiveness, prioritize staying below rate limits.
Filter to items where sellerCentralConnection is not null.
2. Fetch export sources (get source ID)
GET /api/v1/exports/sources?sellerOrVendorIds=<sellerId>
Find the source named Order Line Items (type SELLER_CENTRAL) and use the id it returns — always prefer the resolved id.
Never hardcode the source id: resolve it at runtime from GET /api/v1/exports/sources by matching tableName == "amazon_order_items_with_cogs" (the id format can differ between the REST and MCP surfaces).
To filter by status, add filters. Use beginsWith for Shipped and Unshipped so marketplace-prefixed variants (Shipped* / Unshipped*) are included; = is safe only for Pending and Canceled:
When status is COMPLETED, download. If ERROR, show error.
GET /api/v1/exports/<exportId>/raw
200: redirects (302) to a pre-signed S3 URL — axios must follow the redirect automatically (followRedirects: true in Vite proxy handles this on the server side; the browser axios instance follows it natively).
204: still processing — retry after a few seconds.
The /raw endpoint returns a flat array of line items. Each element is one order item (amazon_order_item_id) within one order. An order with N order items produces N rows all sharing the same amazon_order_id; the same sku can appear on more than one of them.
CRITICAL — columns: [] (empty array) does NOT return all columns. It returns only seller-context metadata columns (seller id / name, marketplace, connection ids) and none of the Order Line Items fields (amazon_order_id, sku, amazon_order_status, etc.). Always specify the required columns explicitly. Every response also prepends those utility columns before your requested fields, so read values by key/name, never by column position.
Field roles:
Field
Level
Notes
amazon_order_id
Order
Grouping key — unique per order
amazon_order_item_id
Line item
Amazon's order-item id — unique per line, never null. Use it as the row key (TanStack getRowId).
amazon_order_status
Order
Consistent across all rows for the same order. Pending / Unshipped / Shipped / Canceled; some marketplaces prefix Shipped* / Unshipped*
fulfillment_channel
Order
Consistent across all rows for the same order
date
Order
Purchase date. Marketplace orders use the marketplace local date. Off-Amazon lines use the kept connection's country time zone. Use this for display and sorting. order_date duplicates date.
sales_channel
Order
Amazon's supplied channel. A marketplace order uses an Amazon marketplace domain, such as Amazon.com. Any other non-empty value, including Non-Amazon, is off-Amazon Multi-Channel Fulfillment. That value does not name the external store. A blank channel is not off-Amazon.
sku
Line item
Seller SKU of the line. Not unique within an order — the same SKU can be a separate order item more than once, so never key rows by it
line_item_number
Line item
Occurrence index of the same SKU within the order (0 for the first line of each SKU; increments only when that SKU repeats). Not the line's position in the order — do not use it to order or key lines
child_asin
Line item
Amazon ASIN
product_name
Line item
Full product name
item_status
Line item
Can differ from amazon_order_status
quantity
Line item
Units for this SKU only
item_price_value
Line item
Line-item total value — already includes quantity; use as-is, do NOT multiply by quantity.Null on cancelled lines (and on orders <4h old): coalesce to 0 and render "—" with a "cancelled" badge, never NaN. On an off-Amazon line this is the order-report amount, not verified sales.
item_price_currency
Line item
Consistent across the priced rows of an order; null on cancelled lines — take it from another line of the same order, else fall back to the marketplace currency
How to build the parent (order) row from the flat array:
typescript
1// Group by amazon_order_id. Sort parent rows by date (purchase date).2// item_price_value is already the line TOTAL - sum it as-is, never multiply by quantity.3// item_price_value and item_price_currency are NULL on cancelled lines (and on orders <4h old):4// coalesce the price to 0 and take the currency from the first line that has one, so a5// cancelled line can never turn the order total into NaN.6const ordersMap = newMap<string, OrderRow>();
78for (const item of lineItems) {
9const linePrice = item.item_price_value ?? 0; // null on cancelled lines -> 0, never NaN10const existing = ordersMap.get(item.amazon_order_id);
11if (existing) {
12 existing.lineItems.push(item); // child rows are keyed by amazon_order_item_id, not sku13 existing.totalPrice += linePrice; // line total, NOT × quantity14 existing.itemCount += item.quantity ?? 0;
15 existing.currency ??= item.item_price_currency ?? null; // first non-null currency wins16 } else {
17 ordersMap.set(item.amazon_order_id, {
18amazon_order_id: item.amazon_order_id,
19amazon_order_status: item.amazon_order_status, // order-level, consistent20fulfillment_channel: item.fulfillment_channel, // order-level, consistent21sales_channel: item.sales_channel, // order-level, consistent22date: item.date, // local date in the kept connection's country time zone23currency: item.item_price_currency ?? null, // null on cancelled lines; filled from a later line24totalPrice: linePrice, // line total, NOT × quantity25itemCount: item.quantity ?? 0,
26lineItems: [item],
27 });
28 }
29}
3031const orders = Array.from(ordersMap.values());
32// Sort by date descending. date is the purchase date. order_date is the same value.33// If currency is still null (every line cancelled), fall back to the seller's marketplace34// currency (e.g. GBP for Amazon.co.uk) and render the total as "—" with a "cancelled" badge.
Parent row columns to display:
Column
Source
Display
Order ID
amazon_order_id
Monospace, full string
Order Date
date
Purchase date
Status
amazon_order_status (first item)
Coloured badge
Channel
fulfillment_channel (first item)
Badge
Sales channel
sales_channel (first item)
Amazon domain, or the supplied off-Amazon value
Items
sum(quantity) across all line items
Number
Total
sum(item_price_value ?? 0) (already line totals; null on cancelled lines)
Formatted currency; "—" + "cancelled" badge when every line is null. For an off-Amazon order, label it as a declared amount, not sales revenue.
Tags
localStorage only
Tag chips
Child (line item) row columns to display (row key: amazon_order_item_id via TanStack getRowId — not sku, not the array index):
Column
Source
SKU
sku
ASIN
child_asin
Product
product_name
Qty
quantity
Price
item_price_value + item_price_currency ("—" when null, i.e. cancelled line)
Item Status
item_status
An order is off-Amazon when sales_channel is non-empty and, after trim and lowercasing, is not an Amazon marketplace domain: amazon.ae, amazon.ca, amazon.co.jp, amazon.co.uk, amazon.co.za, amazon.com, amazon.com.au, amazon.com.be, amazon.com.br, amazon.com.mx, amazon.com.tr, amazon.de, amazon.eg, amazon.es, amazon.fr, amazon.ie, amazon.in, amazon.it, amazon.nl, amazon.pl, amazon.sa, amazon.se, or amazon.sg. Keep the row and the supplied channel. A blank channel stays a marketplace order. Do not name an external store from a generic value such as Non-Amazon.
CRITICAL — API parameter formats discovered through testing:
GET /exports/sources uses bare query param sellerOrVendorIds=<uuid> — notsellerOrVendorIds[]=<uuid> and notsellerOrVendorIds[0]=<uuid>. The bracket syntax is rejected with 400.
POST /exportscolumns must be an explicit list of the field names you need — never pass [] (empty). An empty array returns only seller-context metadata with no order fields, causing the table to display empty rows.
Date range uses top-levelfrom and to fields (ISO 8601 datetime strings like 2025-01-01T00:00:00.000Z) — not inside filters.
filters uses combinator with lowercase values: "and" or "or" (not "AND" / "OR").
Each filter rule must include the not field (boolean): { "field": "...", "operator": "...", "value": "...", "not": false }.
If no filter rules are needed, either omit filters entirely or pass { "combinator": "and", "rules": [] }.
Default Tech Stack (Low-Level Agents Only)
Skip this section if you are a high-level assistant.
Implement app code using exact snippets from the Mandatory Code Snippets section.
Run build/lint checks.
File Structure (Feature-Based)
Every component lives in its own directory containing exactly two files: the component file and its CSS Module. No component files sit loose in a parent folder.
Expected: HTTP/2 200. Continue only when direct check returns HTTP 200.
If 403: wrong API key for the target. If 502: DNS/network issue. Stop and fix before coding.
Step 2: Local Proxy Verification (after npm run dev)
After starting the dev server, read its output to find the actual port (may not be 5173 if that port is in use), then run:
Expected: HTTP/1.1 200 OK. Finish only when localhost proxy check also returns HTTP 200.
Debug Path for 403/502
If either check fails, follow this mandatory debug strategy:
502 + ENOTFOUND: proxy target DNS/network mismatch. Verify VITE_PROXY_TARGET is exactly https://api.datadoe.com and that the process has network access. If running in a sandbox, restart with full network permissions.
502 on wrong localhost port: check actual Vite port from terminal output and retry on the correct port.
403: API key/target environment mismatch (e.g., staging key used against production target). Verify the API key matches the target.
After any fix, re-run both checks (direct target and localhost proxy).
Mandatory Code Snippets
The following files must be implemented exactly as shown. These are verified working against the production API. Do not modify the proxy configuration, base URL logic, header logic, or request parameter shapes.
Why this works: The browser sends requests to /api/v1/... on localhost. Vite's dev server proxies them to https://api.datadoe.com/api/v1/.... changeOrigin: true sets the Host header to the target. secure: true enforces TLS verification. followRedirects: true handles any 3xx from the API.
src/api/client.ts — Axios Instance with Pacing & 429 Retry
BASE_URL is always /api (from .env), never a full URL — all requests go through the Vite proxy.
Auth headers use datadoe-api-key (not datadoe-organization-id) when both are available. Never send both.
The pacing interceptor enforces 600ms minimum between requests (< 2 req/s limit).
The 429 interceptor reads Retry-After, waits, and retries once.
src/api/datadoe.ts — API Functions with Correct Request Shapes
typescript
1import client from"./client";
23// The Order Line Items source id is resolved at runtime from GET /exports/sources4// by table name. Never hardcode it: ids differ between the REST and MCP surfaces and5// can change; a stale id fails the export with FIELD/SOURCE errors.6const ORDER_LINE_ITEMS_TABLE = "amazon_order_items_with_cogs";
78exportasyncfunctionfetchSellersAndVendors() {
9const response = await client.get<{ items: any[] }>(
10"/v1/util/sellers-and-vendors"11 );
12return response.data.items;
13}
1415// IMPORTANT: query param is sellerOrVendorIds=<uuid> (no brackets)16exportasyncfunctionfetchOrderLineItemsSourceId(17 sellerId: string18): Promise<string> {
19try {
20const response = await client.get<any[]>(
21`/v1/exports/sources?sellerOrVendorIds=${sellerId}`22 );
23const orderSource = response.data.find(
24(s: any) =>25 s.tableName === ORDER_LINE_ITEMS_TABLE ||
26 (s.name === "Order Line Items" && s.type === "SELLER_CENTRAL")
27 );
28if (!orderSource?.id) {
29thrownewError(
30`Source ${ORDER_LINE_ITEMS_TABLE} not found for seller ${sellerId} - check the connection and the Data settings.`31 );
32 }
33return orderSource.id;
34 } catch (error) {
35// Surface the failure in the UI; do not fall back to a hardcoded id.36throw error;
37 }
38}
3940// Required columns for the Order Line Items source.41// NEVER pass columns: [] — an empty array returns only seller-context metadata42// (seller_or_vendor_id, seller_or_vendor_name, marketplace_country_name, etc.) with NO order fields,43// which causes the table to display empty rows.44const ORDER_LINE_ITEMS_COLUMNS = [
45"amazon_order_id",
46"amazon_order_item_id", // unique per line - the row key (sku can repeat within an order)47"date",
48"amazon_order_status",
49"fulfillment_channel",
50"sales_channel",
51"sku",
52"line_item_number",
53"child_asin",
54"product_name",
55"item_status",
56"quantity",
57"item_price_value",
58"item_price_currency",
59];
6061// IMPORTANT: export creation request shape — all fields are mandatory.62// - from/to are TOP-LEVEL ISO datetime strings (not inside filters).63// - columns must be an EXPLICIT list of field names (never empty []).64// - sendToAllOrganizationMembers is required (use false).65// - filters.combinator is lowercase: "and" or "or".66// - each filter rule must have a "not" boolean field.67exportasyncfunctioncreateExport(68 sellerId: string,
69 sourceId: string,
70 dateFrom: string,
71 dateTo: string,
72 orderStatusFilters: string[] = []
73) {
74const body: Record<string, unknown> = {
75 sourceId,
76sellerOrVendorIds: [sellerId],
77outputType: "JSON",
78columns: ORDER_LINE_ITEMS_COLUMNS,
79sendToAllOrganizationMembers: false,
80from: `${dateFrom}T00:00:00.000Z`,
81to: `${dateTo}T23:59:59.999Z`,
82 };
8384if (orderStatusFilters.length > 0) {
85 body.filters = {
86combinator: "or",
87rules: orderStatusFilters.map((status) => ({
88field: "amazon_order_status",
89// Shipped / Unshipped have marketplace-prefixed variants (Shipped*, Unshipped*):90// match them with beginsWith. Pending / Canceled are exact values.91operator:
92 status === "Shipped" || status === "Unshipped" ? "beginsWith" : "=",
93value: status,
94not: false,
95 })),
96 };
97 }
9899const response = await client.post<any>("/v1/exports", body);
100return response.data;
101}
102103exportasyncfunctionpollExport(exportId: string) {
104const response = await client.get<any>(`/v1/exports/${exportId}`);
105return response.data;
106}
107108exportasyncfunctionfetchExportRaw(exportId: string) {
109const response = await client.get(`/v1/exports/${exportId}/raw`, {
110validateStatus: (status) => status === 200 || status === 204,
111 });
112if (response.status === 204) returnnull;
113return response.data;
114}
.env.example
bash
1# Vite proxies /api → https://api.datadoe.com (CORS bypass for local dev)2VITE_API_BASE_URL=/api
3VITE_PROXY_TARGET=https://api.datadoe.com
4VITE_DATADOE_API_KEY=<your-api-key>
Implementation Rules
Single run: the app must work after one execution. Do not leave TODOs or placeholders.
Test API calls first: before coding the full UI, verify the export flow works by running the mandatory connectivity checks.
Group line items by order: the API returns flat rows. Group by amazon_order_id before rendering.
Handle empty states: no sellers, no orders, export still loading — all need UI.
Date defaults: from = 30 days ago, to = today.
Use outputType: "JSON" for exports.
Poll interval: 5 seconds between status checks. Timeout after 2 minutes with an error message.
Retry on 429: auto-retry with the Retry-After value, with incrementally increasing delays.
Use the exact code snippets from the Mandatory Code Snippets section for vite.config.ts, src/api/client.ts, and src/api/datadoe.ts.
Run build and lint before finalizing.
Leave dev server running in background after implementation.
Report local URL, proxy check result, and any residual risk explicitly.
Protected Files
Never modify .env.
Use .env.example as reference and documentation target.
Never print .env secrets in output.
Post-Implementation Startup
Always run dev server in background:
bash
1npm run dev
Verification Checklist
After implementation, verify:
App starts without errors (npm run dev).
Seller picker loads and shows sellers.
Selecting a seller and clicking "Load Orders" triggers the export flow.
Orders appear in the table grouped by amazon_order_id.
Expanding a row shows line items.
Date filter changes trigger new exports.
Status filter with checkboxes works.
Tags can be added, removed, and persist across page reloads.