Use Cases & Recipes

Six things distributors and brands build on the SpireStock API, each with the exact endpoints and working code. Pick the one that matches your integration and start from its recipe.

💡

Before you start

Every recipe uses an API key sent as the X‑API‑Key header. A read key is enough to pull data; pushing data back needs a write key. See Getting Started to create one, and What You Can Build for the full map of endpoint groups.

1. Sync orders with your ERPTwo-way orders between SAP/Tally and SpireStock 2. Bulk-load master dataPush outlets, SKUs and price lists from your system 3. Feed a BI warehouseScheduled sales & stock exports into your analytics 4. Capture secondary salesReport distributor-to-retailer sell-out 5. Read field-force activityVisits, beat productivity and rep performance 6. Answer questions with AILet Claude or Cursor read the workspace (MCP)

1. Sync orders with your ERP

Goal: pull new SpireStock orders into SAP, Oracle or Tally, and push their fulfilment status back — without anyone re-keying anything.

Endpoints: GET /orders (poll for new), GET /orders/{id} (full detail), PATCH /orders/{id}/status (write status back).

Pull orders placed since your last sync

GET /orders accepts date_from, date_to, status, page and limit. status is the same number as the writeback below (3 = approved). Store the timestamp of your last run and ask only for what is new:

curl "https://api.spirestock.com/api/v1/orders?date_from=2026-09-01&status=3&limit=100" \
  -H "X-API-Key: df_your_read_key"

The response is paginated — loop on page until pagination.total_pages is reached, so a busy day never silently drops orders past the first 100.

Write fulfilment status back

When your ERP marks an order delivered, reflect it in SpireStock with a write key. Status is a number: 1 initiated, 2 forwarded, 3 approved, 4 delivered.

curl -X PATCH "https://api.spirestock.com/api/v1/orders/4821/status" \
  -H "X-API-Key: df_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": 4 }'

✅

Prefer push over poll

Polling GET /orders works, but for near-real-time sync register a webhook on order.created and order.delivered instead. SpireStock then calls your endpoint the moment an order changes, so you only fetch detail when there is something to fetch.

2. Bulk-load master data

Goal: keep outlets, SKUs, areas and price lists in SpireStock in step with the system of record on your side.

Endpoints: the /masters/* family — POST /masters/outlets, POST /masters/areas, POST /masters/brands and 40+ more, plus the /imports/* endpoints for spreadsheet-shaped bulk loads (/imports/rate-list, /imports/schemes, /imports/product-variants).

Create an outlet

curl -X POST "https://api.spirestock.com/api/v1/masters/outlets" \
  -H "X-API-Key: df_your_write_key" \
  -H "Content-Type: application/json" \
  -d '{ "outlet_name": "Sharma Kirana", "route_id": 12, "town_id": 5, "phone": "9876543210" }'

Idempotent upserts

Loading the same catalogue nightly? Fetch first (GET /masters/outlets), diff against your source, and only POST what is new or PUT what changed. The API does not dedupe by name for you, so a blind re-POST creates duplicates.

3. Feed a BI warehouse

Goal: land sales, stock and activity data in Snowflake, BigQuery or a spreadsheet on a schedule.

Endpoints: GET /reports/sales and the report family for aggregates; GET /exports/* for file-shaped extracts (/exports/orders, /exports/secondary-sales, /exports/ledger, /exports/products); GET /dashboard/stats for a headline snapshot.

Nightly order export as a file

GET /exports/orders takes format (xlsx or pdf), status, date_from and date_to, and returns the file directly — pipe it straight to your warehouse loader:

curl "https://api.spirestock.com/api/v1/exports/orders?format=xlsx&date_from=2026-09-22&date_to=2026-09-22" \
  -H "X-API-Key: df_your_read_key" \
  -o orders-2026-09-22.xlsx

Aggregates without the rows

For a dashboard tile rather than a full extract, GET /reports/sales returns totals and a per-user breakdown in one call, so you do not have to sum orders client-side.

4. Capture secondary sales

Goal: record what distributors sell on to retailers (sell-out), not just what you ship to distributors (sell-in) — the number brands actually plan against.

Endpoints: GET /secondary-sales to read, POST /secondary-sales to record, and GET /exports/secondary-sales for a filtered extract.

curl "https://api.spirestock.com/api/v1/secondary-sales?date_from=2026-09-01" \
  -H "X-API-Key: df_your_read_key"

💡

Why this matters for FMCG

Sell-in tells you what left your warehouse; sell-out tells you what the market actually consumed. Feeding secondary sales into your demand planning is how you stop stocking distributors that are sitting on inventory.

5. Read field-force activity

Goal: pull rep visits, beat-plan adherence and productivity into your own performance dashboards.

Endpoints: GET /visits for outlet visits, GET /beat-plans for planned routes, and GET /reports/beat-productivity for the scored rollup.

curl "https://api.spirestock.com/api/v1/reports/beat-productivity?date=2026-09-22&user_id=42" \
  -H "X-API-Key: df_your_read_key"

This report is scored per day — pass date (one day, defaults to today) and optionally user_id for a single rep. For a month, call it per day and aggregate on your side, or use GET /exports/beat-productivity for a file.

Live rep location is available under /tracking/* (/tracking/live) if you are building a real-time map rather than a historical report.

6. Answer questions with AI

Goal: let a non-technical user — a sales head, an account manager — ask the workspace questions in plain language, without anyone writing a query.

Instead of the REST API, connect an assistant over MCP. It wraps a read key and exposes the workspace to Claude, Cursor or any MCP client as a set of read-only tools:

claude mcp add --env SPIRESTOCK_API_KEY=df_your_read_key --transport stdio spirestock -- npx -y @spirestock/mcp-server

Then ask, in the assistant:

“Which outlets in the north beat haven’t ordered in 30 days?”
“Compare this month’s delivered orders to last month.”
“What are my top five SKUs by revenue this quarter?”

⚠️

Read-only, by design

MCP can look at orders, accounts, products and reports, but never place an order, change a record or touch billing. When you need to write, that is a REST integration with a write key — see recipe 1. Full setup is on the Connect AI Tools page.

Where to go next

API Reference — every endpoint, parameter and response schema, with a live Try It bar.
Webhooks — react to events instead of polling.
SDKs — Node.js and Python client examples.