Line Items

Line Items form the core of every Procurement Scorecard. Each line item represents an amount of spend allocated to a specific supplier for the defined reporting period. Line item amounts must exclude VAT. These records drive all downstream B-BBEE procurement calculations, including TMPS, recognition levels, and ownership weighting.

Line items are append-only: the API supports creating and reading line items, but does not allow updates or deletions. To correct a mistake, you must create a new line item that reflects the corrected spend.

You may insert line items individually or in bulk in a single request.

---

Endpoints

Method	Path	Purpose
GET	/api/v1/procurement_scorecards/{procurement_scorecard_id}/heartbeat	Confirm API availability and authentication
GET	/api/v1/procurement_scorecards/{procurement_scorecard_id}/line_items	Retrieve all line items for the given scorecard
POST	/api/v1/procurement_scorecards/{procurement_scorecard_id}/line_items	Create one or more line items

Authentication

Include the following headers on every request:

• Authorization: HMAC <signature>
• X-Api-Key: <your account key>
• Accept: application/json

See Authentication.

---

Attributes

Field	Type	Required	Description
supplier_vendor_code	string	yes	The supplier's vendor code. Must match an existing supplier you have created.
spend	number	yes	Spend amount for the given scorecard period. Excluding VAT.

System Fields (Response Only)

Field	Type	Description
id	string	Line item identifier.
supplier_trading_name	string	Trading name of the linked supplier.
created_at	string	Creation timestamp (DD/MM/YYYY HH:MM:SS).
updated_at	string	Last update timestamp (DD/MM/YYYY HH:MM:SS).

---

Notes

• Line items cannot be updated or deleted after creation.
• Use bulk create (multiple items in one request) for high-volume data loads.
• Every line item must reference a valid supplier via supplier_vendor_code.

---

List line items

Retrieve all line items for a procurement scorecard.

GET /api/v1/procurement_scorecards/{procurement_scorecard_id}/line_items

Path parameters

Name	Type	Required	Description
procurement_scorecard_id	string	yes	The procurement scorecard identifier.

Code examples

cURL

curl -X GET "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards/100/line_items" \
  -H "Accept: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>"

JavaScript (axios)

const url =
  "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards/100/line_items";
const path = new URL(url).pathname;
const signature = await generateSignature(path, "", apiSecret, 5);

const response = await axios.get(url, {
  headers: {
    Accept: "application/json",
    Authorization: `HMAC ${signature}`,
    "X-Api-Key": apiKey,
  },
});

console.log(response.data);

Response

[
  {
    "spend": "1000.0",
    "id": "3311",
    "created_at": "16/02/2026 08:01:32",
    "updated_at": "16/02/2026 08:01:32",
    "supplier_vendor_code": "afr001",
    "supplier_trading_name": "African Reinforcing Construction"
  }
]

---

Create line items

Create one or more line items for a procurement scorecard.

POST /api/v1/procurement_scorecards/{procurement_scorecard_id}/line_items

Path parameters

Name	Type	Required	Description
procurement_scorecard_id	string	yes	The procurement scorecard identifier.

Request body

Send a JSON object with a line_items array:

{
  "line_items": [
    {
      "supplier_vendor_code": "afr001",
      "spend": 1000
    }
  ]
}

Code examples

cURL

curl -X POST "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards/100/line_items" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your account key>" \
  -H "Authorization: HMAC <your signature>" \
  -d '{
    "line_items": [
      {
        "supplier_vendor_code": "afr001",
        "spend": 1000
      }
    ]
  }'

JavaScript (axios)

const url =
  "https://www.suppliermanagement.co.za/api/v1/procurement_scorecards/100/line_items";
const payload = {
  line_items: [
    {
      supplier_vendor_code: "afr001",
      spend: 1000,
    },
  ],
};

const path = new URL(url).pathname;
const signature = await generateSignature(path, payload, apiSecret, 5);

const response = await axios.post(url, payload, {
  headers: {
    Accept: "application/json",
    Authorization: `HMAC ${signature}`,
    "X-Api-Key": apiKey,
  },
});

console.log(response.data);

Response

[
  {
    "spend": "1000.0",
    "id": "3311",
    "created_at": "16/02/2026 08:01:32",
    "updated_at": "16/02/2026 08:01:32",
    "supplier_vendor_code": "afr001",
    "supplier_trading_name": "African Reinforcing Construction"
  }
]