Bearer TokenNo token

API Reference

The SpireStock REST API lets you programmatically manage orders, users, products, and workspace settings for your sales & distribution operations.

Base URL

https://api.spirestock.com/api/v1

Authentication

All API requests (except login and signup) require a valid JWT Bearer token in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Obtain a token via the login or OTP verification endpoints. Tokens expire after 15 days. Re-authenticate by calling the login endpoint again when you receive a 401 Unauthorized response.

Rate Limits

The API enforces rate limits per IP and per authenticated user:

General endpoints: 120 requests/min, 2,000 requests/hour
Login / OTP: 20 requests per 15 minutes (IP-based)
Signup: 5 requests per hour (IP-based)
Export endpoints: 5 requests/min, 50 requests/hour
Report endpoints: 20 requests/min, 200 requests/hour

When rate-limited you will receive a 429 Too Many Requests response with a Retry-After header.

Error Format

{
  "response_code": 400,
  "message": "Validation failed"
}

Pagination

List endpoints return paginated results. Use page and limit query parameters. The response includes a pagination object with total, total_pages, page, and limit.

Authentication

POST/auth/login

Authenticate with email and password. Returns a JWT token, user profile, navigation modules, and workspace details.

Request Body

Name	Type	Required	Description
`email`	string	Yes	User email address
`password`	string	Yes	Account password

curl -X POST https://api.spirestock.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password"
  }'

POST/auth/otp/request

Request a one-time password sent via SMS for passwordless login.

Request Body

Name	Type	Required	Description
`phone`	string	Yes	Phone number to receive OTP

curl -X POST https://api.spirestock.com/api/v1/auth/otp/request \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210"
  }'

POST/auth/otp/verify

Verify the OTP and receive a JWT token. Completes passwordless authentication.

Request Body

Name	Type	Required	Description
`phone`	string	Yes	Phone number used in OTP request
`otp`	string	Yes	The OTP code received via SMS

curl -X POST https://api.spirestock.com/api/v1/auth/otp/verify \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "otp": "482910"
  }'

GET/auth/me

Retrieve the authenticated user’s profile, role, and organization context.

curl https://api.spirestock.com/api/v1/auth/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Signup

POST/signup/register

Request Body

Name	Type	Required	Description
`first_name`	string	Yes	First name of the admin user
`last_name`	string	Yes	Last name of the admin user
`official_email`	string	Yes	Admin email address
`primary_contact_number`	string	Yes	Admin phone number
`password`	string	Yes	Password (min 8 characters)
`organization_name`	string	Yes	Name of the organization/business

curl -X POST https://api.spirestock.com/api/v1/signup/register \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Jane",
    "last_name": "Smith",
    "official_email": "[email protected]",
    "primary_contact_number": "+919876543210",
    "password": "secureP@ss123",
    "organization_name": "Acme Dairy"
  }'

Orders

GET/orders

List orders with pagination, filtering by status, date range, user, and search query. Status values are integers: 1 (initiated), 2 (forwarded), 3 (approved), 4 (delivered).

Parameters

Name	Type	Required	Description
`page`	number	No	Page number (default: 1)(default: 1)
`limit`	number	No	Items per page (default: 20, max: 100)(default: 20)
`status`	number	No	Filter by status: 1 (initiated), 2 (forwarded), 3 (approved), 4 (delivered)
`date_from`	string	No	Start date (YYYY-MM-DD)
`date_to`	string	No	End date (YYYY-MM-DD)
`user_id`	number	No	Filter orders by a specific user ID
`search`	string	No	Search by order code or user name

curl "https://api.spirestock.com/api/v1/orders?page=1&limit=20&status=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST/orders

Create a new order. Items are specified as an array of product variant IDs with quantities.

Request Body

Name	Type	Required	Description
`user_id`	number	Yes	The customer (retailer/distributor) user ID
`items`	array	Yes	Array of { product_variant_id, quantity }
`order_date`	string	No	Order date (YYYY-MM-DD)
`delivery_date`	string	No	Requested delivery date (YYYY-MM-DD)

curl -X POST https://api.spirestock.com/api/v1/orders \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 42,
    "items": [
      { "product_variant_id": 10, "quantity": 20 },
      { "product_variant_id": 15, "quantity": 10 }
    ],
    "delivery_date": "2026-06-02"
  }'

GET/orders/{id}

Retrieve a single order by ID, including items, user details, and delivery info.

Parameters

Name	Type	Required	Description
`id`	number	Yes	Order ID (integer)

curl https://api.spirestock.com/api/v1/orders/142 \
  -H "Authorization: Bearer YOUR_TOKEN"

PATCH/orders/{id}/status

Update the status of an order. Status flow: 1 (initiated) → 2 (forwarded) → 3 (approved) → 4 (delivered).

Parameters

Name	Type	Required	Description
`id`	number	Yes	Order ID (integer)

Request Body

Name	Type	Required	Description
`order_status`	number	Yes	New status: 2 (forwarded), 3 (approved), or 4 (delivered)

curl -X PATCH https://api.spirestock.com/api/v1/orders/142/status \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "order_status": 3
  }'

Users

GET/users

List all users in the organization with pagination and type filtering. User types: 0 (admin), 1 (employee), 2 (distributor).

Parameters

Name	Type	Required	Description
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 20, max: 100)
`type`	string	No	Filter by type: admin, employee, distributor
`search`	string	No	Search by name, email, or phone
`status`	number	No	Filter by status: 1 (active), 0 (inactive)

curl "https://api.spirestock.com/api/v1/users?type=distributor&page=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST/users

Create a new user in the organization. User type determines their role in the system.

Request Body

Name	Type	Required	Description
`first_name`	string	Yes	First name
`last_name`	string	Yes	Last name
`official_email`	string	No	Email address
`primary_contact_number`	string	Yes	Phone number
`password`	string	Yes	Initial password
`role_id`	number	Yes	Role ID
`user_type`	number	Yes	User type: 0 (admin), 1 (employee), 2 (distributor)

curl -X POST https://api.spirestock.com/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Priya",
    "last_name": "Singh",
    "official_email": "[email protected]",
    "primary_contact_number": "+919123456789",
    "password": "secureP@ss123",
    "role_id": 3,
    "user_type": 2
  }'

GET/users/{id}

Retrieve a single user profile by ID, including role and organization details.

Parameters

Name	Type	Required	Description
`id`	number	Yes	User ID (integer)

curl https://api.spirestock.com/api/v1/users/42 \
  -H "Authorization: Bearer YOUR_TOKEN"

Products

GET/products

List all products in the catalog with optional search filter. Products include their class and variants.

Parameters

Name	Type	Required	Description
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 20, max: 100)
`search`	string	No	Search by product name
`status`	number	No	Filter by status: 1 (active), 0 (inactive)

curl "https://api.spirestock.com/api/v1/products?search=milk&status=1" \
  -H "Authorization: Bearer YOUR_TOKEN"

POST/products

Add a new product to the catalog with optional variants.

Request Body

Name	Type	Required	Description
`product_name`	string	Yes	Product name
`product_class_id`	number	Yes	Product class/category ID
`product_hsn`	string	No	HSN code for tax classification
`product_description`	string	No	Product description
`variants`	array	No	Array of { variant_name, item_sku_code, mrp, sp } variant objects

curl -X POST https://api.spirestock.com/api/v1/products \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Toned Milk",
    "product_class_id": 1,
    "product_hsn": "0401",
    "variants": [
      { "variant_name": "500ml", "item_sku_code": "TM-500", "mrp": 25.00, "sp": 22.00 },
      { "variant_name": "1L", "item_sku_code": "TM-1000", "mrp": 48.00, "sp": 42.00 }
    ]
  }'

Dashboard

GET/dashboard/stats

Retrieve summary statistics for the organization dashboard including order counts by status, employee metrics, revenue, and collection data.

curl https://api.spirestock.com/api/v1/dashboard/stats \
  -H "Authorization: Bearer YOUR_TOKEN"

GET/dashboard/monthly-sales

Retrieve product-wise sales data with daily trends, monthly totals, and year-over-year comparison. Returns data grouped by product class.

curl https://api.spirestock.com/api/v1/dashboard/monthly-sales \
  -H "Authorization: Bearer YOUR_TOKEN"

Exports

GET/exports/orders

Export orders as XLSX or PDF. Supports status and date range filters.

Parameters

Name	Type	Required	Description
`format`	string	No	Export format: xlsx (default) or pdf(default: xlsx)
`status`	number	No	Filter by order status (1-4)
`date_from`	string	No	Start date (YYYY-MM-DD)
`date_to`	string	No	End date (YYYY-MM-DD)
`production_unit_id`	number	No	Filter by production unit

curl "https://api.spirestock.com/api/v1/exports/orders?format=xlsx&date_from=2026-05-01&date_to=2026-05-31" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o orders-export.xlsx

GET/exports/users

Export user list as XLSX or PDF with optional type and status filters.

Parameters

Name	Type	Required	Description
`format`	string	No	Export format: xlsx (default) or pdf(default: xlsx)
`type`	string	No	Filter by user type: admin, employee, distributor
`status`	number	No	Filter by status: 1 (active), 0 (inactive)

curl "https://api.spirestock.com/api/v1/exports/users?format=pdf&type=distributor" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o users-export.pdf

GET/exports/sales

Export sales report as XLSX or PDF. Includes revenue breakdown by product class and trends.

Parameters

Name	Type	Required	Description
`format`	string	No	Export format: xlsx (default) or pdf(default: xlsx)
`date_from`	string	No	Start date (YYYY-MM-DD)
`date_to`	string	No	End date (YYYY-MM-DD)

curl "https://api.spirestock.com/api/v1/exports/sales?format=xlsx&date_from=2026-01-01&date_to=2026-05-31" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o sales-report.xlsx

Workspace

GET/workspace/config

Retrieve the current workspace configuration including branding, organizational details, and operational settings.

curl https://api.spirestock.com/api/v1/workspace/config \
  -H "Authorization: Bearer YOUR_TOKEN"

PUT/workspace/config

Update workspace configuration. Only admin users can modify workspace settings.

Request Body

Name	Type	Required	Description
`logo`	string	No	Logo URL
`primary_color`	string	No	Brand primary color hex code
`secondary_color`	string	No	Brand secondary color hex code
`org_footer_name`	string	No	Organization footer/legal name
`org_address`	string	No	Organization address
`contact_number`	string	No	Contact phone number

curl -X PUT https://api.spirestock.com/api/v1/workspace/config \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "primary_color": "#2563eb",
    "org_footer_name": "Acme Dairy Co. Pvt. Ltd.",
    "contact_number": "+911234567890"
  }'