Imports API

Upload Excel rate lists, free-scheme sheets, outstanding and revised amounts with a validate-first preview and a separate commit.

6 endpointsBase URL https://api.spirestock.com/api/v1

Every request needs an API key or a session token. Last updated .

On this page (6)

POSThttps://api.spirestock.com/api/v1/imports/preview/{type}

Check a product-variant, scheme or variant-price sheet before importing it; nothing is saved. type is product-variants, schemes or rate-list. Headers are matched to the template's columns (case, spacing and text in brackets are ignored). Every row is validated, including that the product, variant or SKU exists. rows holds the first 200 rows as text; valid_rows, invalid_rows and errors (first 100 failing rows) cover the whole file. A missing required column is reported in missing_required, and POST /imports/{type} then answers 400. Upload as multipart/form-data, field file (.xlsx or .csv, max 10 MB). Other file types answer 400 and files over 10 MB answer 413.

Access: API key write scope; staff need Product and Variant Management (17) or Upload Rate List (18) or Upload Free Scheme List (32) — add.

Request body

filefilerequired
The workbook (.xlsx or .csv)
Example request
curl -X POST https://api.spirestock.com/api/v1/imports/preview/schemes \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "[email protected]"
Example response
{
  "response_code": 200,
  "message": "1 row(s) have errors and will be skipped",
  "data": {
    "type": "schemes",
    "file": { "name": "schemes.xlsx", "size": 6692 },
    "sheet": { "name": "Schemes", "total_rows": 2, "total_columns": 6 },
    "columns": [
      { "index": 0, "header": "Name", "key": "name", "label": "Name" },
      { "index": 1, "header": "Scheme Type (1=Free,2=Flat,3=Bulk,4=Quantitative)", "key": "scheme_type", "label": "Scheme Type (1=Free,2=Flat,3=Bulk,4=Quantitative)" }
    ],
    "missing_required": [],
    "unknown_columns": [],
    "valid_rows": 1,
    "invalid_rows": 1,
    "rows": [
      { "row": 2, "cells": ["Summer Offer", "2", "2026-04-01", "2026-06-30", "Toned Milk 1L", "2.5"], "errors": [] },
      { "row": 3, "cells": ["Winter Offer", "9", "", "", "", ""], "errors": ["Scheme Type must be at most 4"] }
    ],
    "preview_truncated": false,
    "errors": [{ "row": 3, "errors": ["Scheme Type must be at most 4"] }]
  }
}

POSThttps://api.spirestock.com/api/v1/imports/rate-list/preview

Rate list, step 1. Columns must be exactly STATE, ZONE, USERTYPE, SKU, CONTAINER RATE. Every row comes back validated with errors[]; nothing is saved. Upload as multipart/form-data, field file (.xlsx or .csv, max 10 MB). Other file types answer 400 and files over 10 MB answer 413.

Access: API key write scope; staff need Upload Rate List (18) — add.

Request body

filefilerequired
The workbook
state_idnumberrequired
State
zone_idsstringrequired
JSON array or comma-separated zone ids
Example request
curl -X POST https://api.spirestock.com/api/v1/imports/rate-list/preview \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@user_rate_list.xlsx" \
  -F "state_id=14" \
  -F "zone_ids=12"
Example response
{
  "response_code": 200,
  "data": {
    "rows": [
      {
        "row": 2,
        "state": "State A",
        "zone": "North Zone",
        "usertype": "2",
        "sku_code": "SKU-009",
        "state_id": null,
        "zone_id": null,
        "user_type": null,
        "product_variant_id": null,
        "product_variant_name": null,
        "no_of_pouch": null,
        "rate": 720,
        "errors": [
          "Invalid state name",
          "zone name mismatch"
        ]
      }
    ],
    "invalid": 0,
    "total": 1,
    "state_id": 14,
    "zone_ids": [
      12
    ]
  }
}

POSThttps://api.spirestock.com/api/v1/imports/rate-list/commit

Step 2: send the preview rows back. Closes the current rate-master rows, creates the new ones and updates every matching customer's per-user price, with history. dry_run reports the counts without saving. Rows with an unknown sku_code, a missing state_id / zone_id or a rate of 0 or less answer 400 "Row 1: invalid state/zone/SKU/rate" (up to five rows listed) and nothing is saved.

Access: API key write scope; staff need Upload Rate List (18) — add.

Request body

rowsarrayrequired
[{ state_id, zone_id, user_type, sku_code, rate }]
dry_runboolean
true to only count
Example request
curl -X POST https://api.spirestock.com/api/v1/imports/rate-list/commit \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "state_id": 14,
        "zone_id": 12,
        "user_type": 2,
        "sku_code": "SKU-009",
        "rate": 720
      }
    ],
    "dry_run": true
  }'
Example response
{
  "response_code": 200,
  "message": "Dry run \u2014 nothing saved",
  "data": {
    "rows": 1,
    "rate_master_closed": 1,
    "rate_master_created": 1,
    "users_matched": 38,
    "user_price_rows_updated": 38,
    "user_price_history_rows": 0,
    "changed_prices": 0,
    "dry_run": true
  }
}

POSThttps://api.spirestock.com/api/v1/imports/free-schemes/preview

Free-scheme sheet, step 1. Columns: SapId, State, Route, Town, Variant Material Code, On Order Of Quantity, Free Variant Material Code, Container Quantity, Pouch Quantity. Rows come back resolved with blocking errors and non-blocking warnings. Step 2, POST /imports/free-schemes/commit, replaces every existing free scheme; skip_invalid saves only valid rows. Upload as multipart/form-data, field file (.xlsx or .csv, max 10 MB). Other file types answer 400 and files over 10 MB answer 413.

Access: API key write scope; staff need Upload Free Scheme List (32) — add.

Request body

filefilerequired
The workbook
Example request
curl -X POST https://api.spirestock.com/api/v1/imports/free-schemes/preview \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@user_scheme.xlsx"
Example response
{
  "response_code": 200,
  "data": {
    "rows": [
      {
        "row": 2,
        "sap_id": "CUST-011",
        "user_id": null,
        "user_name": "Sample User AH",
        "state": "State A",
        "route": "Route A",
        "town": "Town A",
        "state_id": null,
        "route_id": null,
        "town_id": null,
        "variant_material_code": "MAT-001",
        "applied_on_variant_id": null,
        "applied_on_variant_name": null,
        "on_order_of_quantity": 10,
        "free_variant_material_code": "MAT-002",
        "free_variant_id": null,
        "free_variant_name": null,
        "order_container_id": null,
        "order_container_name": null,
        "container_quantity": 0,
        "pouch_quantity": 3,
        "will_create": true,
        "errors": [
          "Invalid state name",
          "Invalid SAP ID"
        ],
        "warnings": [
          "Invalid route name",
          "Invalid town name"
        ]
      }
    ],
    "invalid": 0,
    "total": 1,
    "will_create": 1
  }
}

POSThttps://api.spirestock.com/api/v1/imports/outstanding

Outstanding upload. A multipart file (SAPID, PARTY NAME, AMOUNT) returns a preview and saves nothing; JSON { rows: [{ sap_id, outstanding_amount }] } applies it. /imports/revised-amount works the same way for revised amounts on a day's orders (order_date YYYY-MM-DD).

Access: API key write scope; staff need Upload Outstanding (6) — add.

Request body

rowsarrayrequired
[{ sap_id, outstanding_amount }] — or upload file for a preview
Example request
curl -X POST https://api.spirestock.com/api/v1/imports/outstanding \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rows": [
      {
        "sap_id": "CUST-011",
        "outstanding_amount": 1500
      }
    ]
  }'
Example response
{
  "response_code": 200,
  "message": "Records has been updated successfully.",
  "data": {
    "updated": 1,
    "skipped": [],
    "total": 1
  }
}

GEThttps://api.spirestock.com/api/v1/imports/sheet-template/{type}

Download the Excel template: rate-list (user_rate_list.xlsx) or free-scheme (user_scheme.xlsx).

Access: API key read scope; staff need Product and Variant Management (17) or Upload Rate List (18) or Upload Free Scheme List (32) or Upload Outstanding (6) or Upload Revised Amount (44) or Manage Holidays (43) — add.

Parameters

typestringrequired
rate-list or free-scheme
Example request
curl https://api.spirestock.com/api/v1/imports/sheet-template/rate-list \
  -H "X-API-Key: YOUR_API_KEY"
Example response
(binary .xlsx download)