---
title: "Use Cases & Recipes — SpireStock API"
description: "Worked recipes for building on the SpireStock API: ERP order sync, bulk master import, BI export pipelines, secondary sales, field-force analytics, and AI access over MCP."
source: https://developers.spirestock.com/docs/use-cases
---

# 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](/docs/getting-started#api-keys) to create one, and [What You Can Build](/docs/getting-started#what-you-can-build) for the full map of endpoint groups.

[1\. Sync orders with your ERP Two-way orders between SAP/Tally and SpireStock](#erp-sync)[2\. Bulk-load master data Push outlets, SKUs and price lists from your system](#master-import)[3\. Feed a BI warehouse Scheduled sales & stock exports into your analytics](#bi-pipeline)[4\. Capture secondary sales Report distributor-to-retailer sell-out](#secondary-sales)[5\. Read field-force activity Visits, beat productivity and rep performance](#field-force)[6\. Answer questions with AI Let Claude or Cursor read the workspace (MCP)](#ai-questions)

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

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

```bash
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](/docs/webhooks) 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

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

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

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

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

```bash
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](/docs/mcp) page.

## Where to go next

-   [**API Reference**](/api-reference) — every endpoint, parameter and response schema, with a live Try It bar.
-   [**Webhooks**](/docs/webhooks) — react to events instead of polling.
-   [**SDKs**](/docs/sdks) — Node.js and Python client examples.