---
title: "Imports API — SpireStock REST API"
description: "Upload Excel rate lists, free-scheme sheets, outstanding and revised amounts with a validate-first preview and a separate commit."
source: https://developers.spirestock.com/api-reference/imports
---

# Imports API

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

Base URL: `https://api.spirestock.com/api/v1`. Every request needs an API key (`X-API-Key`) or a session token (`Authorization: Bearer`); see https://developers.spirestock.com/api-reference/auth.

## Endpoints

- [POST /imports/preview/{type}](https://developers.spirestock.com/api-reference/imports#post-imports-preview-type)
- [POST /imports/rate-list/preview](https://developers.spirestock.com/api-reference/imports#post-imports-rate-list-preview)
- [POST /imports/rate-list/commit](https://developers.spirestock.com/api-reference/imports#post-imports-rate-list-commit)
- [POST /imports/free-schemes/preview](https://developers.spirestock.com/api-reference/imports#post-imports-free-schemes-preview)
- [POST /imports/outstanding](https://developers.spirestock.com/api-reference/imports#post-imports-outstanding)
- [GET /imports/sheet-template/{type}](https://developers.spirestock.com/api-reference/imports#get-imports-sheet-template-type)

## POST /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | file | yes | The workbook (.xlsx or .csv) |

**Example request**

```bash
curl -X POST https://api.spirestock.com/api/v1/imports/preview/schemes \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "file=@schemes.xlsx"
```

**Example response**

```json
{
  "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"] }]
  }
}
```

## POST /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | file | yes | The workbook |
| `state_id` | number | yes | State |
| `zone_ids` | string | yes | JSON array or comma-separated zone ids |

**Example request**

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

```json
{
  "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
    ]
  }
}
```

## POST /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `rows` | array | yes | [{ state_id, zone_id, user_type, sku_code, rate }] |
| `dry_run` | boolean | no | true to only count |

**Example request**

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

```json
{
  "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
  }
}
```

## POST /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `file` | file | yes | The workbook |

**Example request**

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

```json
{
  "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
  }
}
```

## POST /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `rows` | array | yes | [{ sap_id, outstanding_amount }] — or upload file for a preview |

**Example request**

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

```json
{
  "response_code": 200,
  "message": "Records has been updated successfully.",
  "data": {
    "updated": 1,
    "skipped": [],
    "total": 1
  }
}
```

## GET /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**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | string | yes | rate-list or free-scheme |

**Example request**

```bash
curl https://api.spirestock.com/api/v1/imports/sheet-template/rate-list \
  -H "X-API-Key: YOUR_API_KEY"
```

**Example response**

```
(binary .xlsx download)
```
