Pricing & Schemes API

Read a customer's price list and per-user prices, preview the schemes an order would earn before placing it, and manage free, new, bulk-pack, quantitative and flat schemes.

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

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

On this page (7)

GEThttps://api.spirestock.com/api/v1/orders/price-list/{userId}

A customer's price list: the variants made at their plant, grouped by class and product, with the per-user price (sp_user per pouch; rate and container_sp_user per crate), MRP, rate_source and validity, plus order shifts, the order cut-off (order_time) and the customer's outstanding amount.

Access: API key read scope; staff need Orders (8) — add.

Parameters

userIdnumberrequired
Customer id
searchstring
Variant name contains
Example request
curl https://api.spirestock.com/api/v1/orders/price-list/44216 \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "message": "Success",
  "user_id": 44216,
  "production_unit_id": 17,
  "product_variant_list": [
    {
      "id": 42,
      "product_class": "Milk",
      "product_hsn": "1001",
      "products": [
        {
          "id": 191,
          "product_name": "Gold",
          "product_variants": [
            {
              "id": 446,
              "product_variant_id": 446,
              "product_id": 191,
              "product_class_id": 42,
              "variant_image": "https://media.example.com/sample.png",
              "rate": 720,
              "sp_user": 30,
              "container_sp_user": 720,
              "mrp": 28,
              "rate_source": "user_price_list",
              "container_id": 43,
              "container_name": "CRATE",
              "packaging_type_id": 43,
              "packaging_type_name": "PCS",
              "item_sku_code": "SKU-009",
              "variant_quantity": 500,
              "variant_unit_id": 18,
              "variant_unit_name": "ML",
              "variant_name": "Gold Milk 500ML",
              "variant_size": "0.5",
              "no_of_pouch": 24,
              "largest_unit_name": "L",
              "is_bulk_pack": 0,
              "included_in_scheme": null,
              "is_allow_in_packaging": 0,
              "is_allow_in_container": 1,
              "container_size": "12.00 L/CRATE",
              "gst": null,
              "valid_from": "2021-12-31",
              "valid_to": "2022-12-31"
            }
          ],
          "products_count": 2
        }
      ],
      "products_count": 13
    }
  ],
  "shift_list": [
    {
      "id": 10,
      "working_shift": "Morning",
      "order_timing": "14:00"
    }
  ],
  "order_time": "14:00",
  "user_outstanding_amount": 0
}

POSThttps://api.spirestock.com/api/v1/orders/calculate-schemes

Scheme preview. Prices a draft order exactly as POST /orders would (customer price list, free, quantitative, flat, bulk-pack and new schemes) and returns lines, applied schemes and totals without saving anything. rate_source on each line says where its rate came from.

Access: API key write scope; staff need Orders (8) — add.

Request body

user_idnumberrequired
Customer id
itemsarrayrequired
[{ product_variant_id, quantity, packaging_type: "0" crates | "1" packets }]
Example request
curl -X POST https://api.spirestock.com/api/v1/orders/calculate-schemes \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": 44663,
    "items": [
      {
        "product_variant_id": 446,
        "quantity": 3,
        "packaging_type": "0"
      },
      {
        "product_variant_id": 453,
        "quantity": 31,
        "packaging_type": "0"
      }
    ]
  }'
Example response
{
  "response_code": 200,
  "data": {
    "header": {
      "user_id": 44663,
      "user_sap_id": "CUST-011",
      "user_name": "Sample User AH",
      "user_type": "Distributor",
      "route_id": 82,
      "route_name": "Route E",
      "town_id": 464,
      "town_name": "Town J",
      "transporter_name": "",
      "transporter_details": "Driver Name: Sample Driver",
      "vehicle_no": "AB01CD1077",
      "production_unit_id": 17,
      "production_unit_name": "North Plant",
      "outstanding_amount": 0,
      "tcs_value": null
    },
    "items": [
      {
        "product_id": 191,
        "product_name": "Gold",
        "product_variant_id": 446,
        "product_variant_name": "Gold Milk 500ML",
        "product_variant_size": "0.5",
        "product_no_of_pouch": 24,
        "product_container_size": "12.00 L/CRATE",
        "product_container_type": "CRATE",
        "product_packaging_type_name": "PCS",
        "quantity_in_pouch": 72,
        "quantity_in_ltr": 36,
        "quantity": 3,
        "rate": 720,
        "amount": 2160,
        "packaging_type": "0",
        "gst": null,
        "is_allow": 0,
        "tally_export_type": 1,
        "rate_source": "user_price_list"
      },
      {
        "product_id": 195,
        "product_name": "Tea special",
        "product_variant_id": 453,
        "product_variant_name": "Tea Special Milk 1000ML",
        "product_variant_size": "1",
        "product_no_of_pouch": 10,
        "product_container_size": "10.00 L/CRATE",
        "product_container_type": "CRATE",
        "product_packaging_type_name": "PCS",
        "quantity_in_pouch": 310,
        "quantity_in_ltr": 310,
        "quantity": 31,
        "rate": 510,
        "amount": 15810,
        "packaging_type": "0",
        "gst": null,
        "is_allow": 0,
        "tally_export_type": 1,
        "rate_source": "user_price_list"
      }
    ],
    "schemes": [],
    "totals": {
      "order_total_amount": 17970,
      "total_incentive": 0,
      "invoice_amount": 17970,
      "crate_total": 0,
      "items_count": 2
    },
    "order_timing": "14:00"
  }
}

GEThttps://api.spirestock.com/api/v1/users/{id}/products

Every per-user price row for a customer. PATCH /users/{id}/products/{variantRowId} with { price } changes one (per pouch; the crate price follows) and records history.

Access: API key read scope; staff need Manage Users (3) — view.

Parameters

idnumberrequired
Customer id
searchstring
SKU, variant or product name contains
Example request
curl https://api.spirestock.com/api/v1/users/44216/products \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": [
    {
      "id": 3849191,
      "organization_id": 6,
      "user_id": 44216,
      "product_id": 201,
      "product_name": "Butter milk Masala",
      "product_variant_id": 437,
      "product_class_id": 48,
      "item_sku_code": "SKU-012",
      "variant_quantity": 200,
      "variant_unit_id": 18,
      "variant_unit_name": "ML",
      "largest_unit_name": "L",
      "variant_name": "Masala Buttermilk 200ML",
      "variant_size": "0.2",
      "no_of_pouch": 60,
      "container_size": "12.00 L/CRATE",
      "is_bulk_pack": 0,
      "included_in_scheme": null,
      "mrp": "10.00",
      "container_mrp": "600.00",
      "sp_user": "7.20",
      "container_sp_user": "432.00",
      "valid_from": "2021-12-31",
      "valid_to": "2022-12-31",
      "status": 1,
      "createdAt": "2023-01-09T05:18:38.000Z",
      "updatedAt": "2024-05-24T06:23:44.000Z"
    }
  ]
}

GEThttps://api.spirestock.com/api/v1/users/{id}/schemes

Schemes a customer is enrolled in (assigned: free, flat, bulkpack, new) and the scheme rows applied on their orders (applied, newest first, each with order_code, order_date and variant names). assigned is always complete; applied is paged by the top-level pagination object (it used to stop silently at 1,000 rows).

Access: API key read scope; staff need Manage Users (3) — view.

Pagedpage and limit (max 100), id as the final sort key. How pagination works

Parameters

idnumberrequired
Customer id
pagenumber
Page number; junk or a value below 1 reads as 1 Default 1.
limitnumber
Page size, default 50, max 100 (larger values are clamped)
Example request
curl https://api.spirestock.com/api/v1/users/44216/schemes \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": {
    "applied": [
      {
        "id": 31330,
        "organization_id": 6,
        "order_id": 310812,
        "scheme_id": 129,
        "user_id": 41507,
        "scheme_type": "free",
        "variant_id": 463,
        "on_order_of": 1,
        "free_variant_id": 499,
        "free_variant_container_type": "CRATE",
        "free_variant_packaging_type": "PCS",
        "free_variant_container_size": "9.90 L/CRATE",
        "container_quantity": 0,
        "pouch_quantity": 2,
        "quantity_in_ltr": "0.33",
        "incentive_amount": null,
        "unit_id": null,
        "unit_name": null,
        "product_id": 197,
        "product_class_id": "42",
        "createdAt": "2023-05-30T13:24:09.000Z",
        "updatedAt": "2023-05-30T13:24:09.000Z",
        "order_code": "ORD0039290",
        "order_date": "2023-05-30T13:24:09.000Z",
        "product_variant": "SKU-001 Milk 500 ml",
        "free_variant_name": "SKU-002 Milk 500 ml"
      }
    ],
    "assigned": {
      "free": [
        {
          "id": 4689,
          "organization_id": 6,
          "user_id": 41507,
          "scheme_id": 129,
          "scheme_name": "SKU-001 Milk 500 ml",
          "state_id": 14,
          "is_route": 0,
          "main_route_id": null,
          "route_id": "79",
          "zone_id": null,
          "town_id": null,
          "scheme_start_date": "2023-03-25",
          "scheme_end_date": "2023-06-30",
          "scheme_type": 1,
          "applied_on_variant_id": 463,
          "applied_on_variant_name": "SKU-001 Milk 500 ml",
          "minimum_order_quantity": 1,
          "packaging_type": 0,
          "order_container_id": 43,
          "order_container_name": "CRATE",
          "order_packaging_id": 43,
          "order_packaging_name": "PCS",
          "free_variant_id": 499,
          "free_variant_name": "SKU-002 Milk 500 ml",
          "container_quantity": 0,
          "pouch_quantity": 2,
          "status": 0,
          "createdAt": "2023-03-25T07:39:33.000Z",
          "updatedAt": "2024-02-02T12:41:26.000Z"
        }
      ],
      "flat": [],
      "bulkpack": [],
      "new": []
    }
  },
  "pagination": {
    "total": 619,
    "page": 1,
    "limit": 2,
    "total_pages": 310
  }
}

GEThttps://api.spirestock.com/api/v1/schemes/admin/lists

All schemes of the five scheme kinds, newest first: free (buy X get Y free), new, bulkpack (slab incentive per unit), quantitative (free goods by order-size slab) and flat (fixed incentive per unit).

Access: API key read scope; staff need Manage Schemes (20) — list.

Example request
curl https://api.spirestock.com/api/v1/schemes/admin/lists \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": {
    "free": [
      {
        "id": 141,
        "organization_id": 6,
        "name": "TS 1000ML",
        "state_id": "14",
        "is_route": 0,
        "route_id": "94",
        "zone_id": null,
        "town_id": null,
        "scheme_start_date": "2023-03-25",
        "scheme_end_date": "2023-06-30",
        "scheme_type": 1,
        "applied_on_variant_id": 463,
        "applied_on_variant_name": "TS 1000ML",
        "minimum_order_quantity": 1,
        "free_variant_id": 499,
        "free_variant_name": "Lite (Milk) 165Ml",
        "container_quantity": 0,
        "pouch_quantity": 2,
        "incentive_amount": null,
        "unit_id": null,
        "unit_name": null,
        "product_class_id": null,
        "status": 0,
        "main_route_id": null,
        "packaging_type": 0,
        "order_container_id": 43,
        "order_container_name": "CRATE",
        "order_packaging_id": 43,
        "order_packaging_name": "PCS",
        "createdAt": "2023-03-25T08:03:14.000Z",
        "updatedAt": "2024-02-02T12:40:48.000Z",
        "route_name": "Route G"
      }
    ],
    "new": [
      {
        "id": 21,
        "organization_id": 6,
        "name": "Route F",
        "state_id": "14",
        "is_route": 0,
        "crate_qty": 0,
        "main_route_id": null,
        "route_id": "82",
        "zone_id": null,
        "town_id": null,
        "products_class": "['42']",
        "scheme_start_date": "2024-03-05",
        "scheme_end_date": "2024-06-30",
        "scheme_type": 2,
        "applied_on_variant_id": "['455', '456', '440', '510', '453', '452', '484']",
        "minimum_order_quantity": 1,
        "packaging_type": 2,
        "order_container_id": 43,
        "order_container_name": "CRATE",
        "order_packaging_id": 43,
        "order_packaging_name": "PCS",
        "free_variant_id": 456,
        "free_variant_name": "Toned Milk 500ML",
        "container_quantity": 1,
        "pouch_quantity": 1,
        "status": 1,
        "createdAt": "2024-03-05T06:22:34.000Z",
        "updatedAt": "2024-03-05T06:46:24.000Z",
        "route_name": "Route E"
      }
    ],
    "bulkpack": [],
    "quantitative": [],
    "flat": []
  }
}

GEThttps://api.spirestock.com/api/v1/schemes/admin/{kind}/{id}

One scheme with its area (route_ids, zone_ids, town_ids) and enrolled users. kind is free, quantitative, bulkpack, new or flat. POST /schemes/admin/{kind} creates one and PUT /schemes/admin/{kind}/{id} updates it.

Access: API key read scope; staff need Manage Schemes (20) — list.

Parameters

kindstringrequired
free, quantitative, bulkpack, new or flat
idnumberrequired
Scheme id
Example request
curl https://api.spirestock.com/api/v1/schemes/admin/free/141 \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": {
    "id": 141,
    "organization_id": 6,
    "name": "TS 1000ML",
    "state_id": "14",
    "is_route": 0,
    "route_id": "94",
    "zone_id": null,
    "town_id": null,
    "scheme_start_date": "2023-03-25",
    "scheme_end_date": "2023-06-30",
    "scheme_type": 1,
    "applied_on_variant_id": 463,
    "applied_on_variant_name": "TS 1000ML",
    "minimum_order_quantity": 1,
    "free_variant_id": 499,
    "free_variant_name": "Lite (Milk) 165Ml",
    "container_quantity": 0,
    "pouch_quantity": 2,
    "incentive_amount": null,
    "unit_id": null,
    "unit_name": null,
    "product_class_id": null,
    "status": 0,
    "main_route_id": null,
    "packaging_type": 0,
    "order_container_id": 43,
    "order_container_name": "CRATE",
    "order_packaging_id": 43,
    "order_packaging_name": "PCS",
    "createdAt": "2023-03-25T08:03:14.000Z",
    "updatedAt": "2024-02-02T12:40:48.000Z",
    "route_ids": [
      94
    ],
    "zone_ids": [],
    "town_ids": [],
    "users": [
      {
        "id": 4789,
        "organization_id": 6,
        "user_id": 42566,
        "scheme_id": 141,
        "scheme_name": "TS 1000ML",
        "state_id": 14,
        "is_route": 0,
        "main_route_id": null,
        "route_id": "94",
        "zone_id": null,
        "town_id": null,
        "scheme_start_date": "2023-03-25",
        "scheme_end_date": "2023-06-30",
        "scheme_type": 1,
        "applied_on_variant_id": 463,
        "applied_on_variant_name": "TS 1000ML",
        "minimum_order_quantity": 1,
        "packaging_type": 0,
        "order_container_id": 43,
        "order_container_name": "CRATE",
        "order_packaging_id": 43,
        "order_packaging_name": "PCS",
        "free_variant_id": 499,
        "free_variant_name": "Lite (Milk) 165Ml",
        "container_quantity": 0,
        "pouch_quantity": 2,
        "status": 0,
        "createdAt": "2023-03-25T08:03:14.000Z",
        "updatedAt": "2024-02-02T12:40:38.000Z",
        "user_name": "Sample User AF",
        "emp_sap_id": "CUST-012",
        "store_name": "Demo Store C",
        "town_name": "Town K",
        "route_name": "Route G",
        "state_name": "State A"
      }
    ]
  }
}

GEThttps://api.spirestock.com/api/v1/schemes/admin/{kind}/{id}/users

The customers assigned to one scheme, with their town, route and state, oldest assignment first. GET /schemes/admin/{kind}/{id} still returns the full set for the edit form.

Access: API key read scope; staff need Manage Schemes (20) — list.

Pagedpage and limit (max 100), id as the final sort key. How pagination works

Parameters

kindstringrequired
free, quantitative, bulkpack, new or flat
idnumberrequired
Scheme id
searchstring
Case-insensitive contains on the user's full name, store name or SAP id; max 100 characters, % and _ match literally
pagenumber
Page number; junk or a value below 1 reads as 1 Default 1.
limitnumber
Page size, default 50, max 100 (larger values are clamped)
Example request
curl "https://api.spirestock.com/api/v1/schemes/admin/free/124/users?limit=50" \
  -H "X-API-Key: YOUR_API_KEY"
Example response
{
  "response_code": 200,
  "data": [
    {
      "id": 4533,
      "organization_id": 6,
      "user_id": 42694,
      "scheme_id": 124,
      "scheme_name": "SKU-001 Milk 500 ml",
      "state_id": 14,
      "is_route": 1,
      "main_route_id": null,
      "route_id": null,
      "zone_id": "12",
      "town_id": "391",
      "scheme_start_date": "2022-08-28",
      "scheme_end_date": "2022-09-28",
      "scheme_type": 1,
      "applied_on_variant_id": 439,
      "applied_on_variant_name": "SKU-001 Milk 500 ml",
      "minimum_order_quantity": 1,
      "packaging_type": 0,
      "order_container_id": 43,
      "order_container_name": "CRATE",
      "order_packaging_id": 43,
      "order_packaging_name": "PCS",
      "free_variant_id": 455,
      "free_variant_name": "SKU-002 Milk 500 ml",
      "container_quantity": 0,
      "pouch_quantity": 1,
      "status": 0,
      "createdAt": "2022-09-02T10:36:21.000Z",
      "updatedAt": "2022-09-03T10:52:25.000Z",
      "user_name": "Sample User A",
      "emp_sap_id": "EMP-001",
      "store_name": "Demo Store A",
      "town_name": "Town A",
      "route_name": "Route A",
      "state_name": "State A"
    }
  ],
  "pagination": {
    "total": 106,
    "page": 1,
    "limit": 2,
    "total_pages": 53
  }
}