Numbers / Spending Methods

Ingest supplier bills as draft transactions in the Numbers module.

Posts a single spending method to the Numbers ledger. The result is a draft transaction (status='d') that surfaces in the existing Mosaic Hub UI (Numbers → Spending Methods) for review, commit, void and VAT processing.

For v1 the only supported type is supplier-bill. Future minor releases (still /v1/) will add more types and indicate them via additive bumps to schema_version.

Required scope

numbers.spending-methods.write

Request

Content-Type: multipart/form-data

SpendingMethodRequest (supplier-bill)

{
  "schema_version": "1.0.0",
  "type": "supplier-bill",
  "bill": {
    "supplier_account_number": "ACME-001",
    "invoice_number": "INV-2026-0042",
    "invoice_date": "2026-05-28",
    "due_date":     "2026-06-27",
    "currency_code": "ZAR",
    "narration": "Office stationery - May 2026",
    "lines": [
      { "description": "Paper, A4",    "quantity": "5", "unit_amount": "100.00", "account_code": "5100", "vat201_rate_code": "20180401-15", "line_total": "500.00" },
      { "description": "Toner, black", "quantity": "1", "unit_amount": "750.00", "account_code": "5100", "vat201_rate_code": "20180401-15", "line_total": "750.00" }
    ],
    "subtotal":  "1250.00",
    "vat_total": "187.50",
    "total":     "1437.50"
  }
}

Validation rules applied server-side:

• All monetary amounts are decimal strings with up to 4 fractional digits.
• currency_code is required on every bill. Must be an ISO 4217 alpha-3 code in uppercase (ZAR, USD, EUR, GBP, ...). The value is persisted to numbers_transaction_headers.transaction_currency; the bill, all line items and the Accounts Payable credit leg post in this single currency.
• line_total is the VAT-exclusive (net) amount per line.
• Sum of line_total must equal subtotal.
• subtotal + vat_total must equal total.
• supplier_account_number must match an active counterparty for the requesting client.
• vat201_rate_code on every line must exist in the Mosaic VAT rate catalogue (see below). Inactive or out-of-window rates are accepted but raise a non-fatal warning in the response.
• schema_version major version must be 1.

VAT rate identifiers

Mosaic exposes a stable, human-meaningful vat201_rate_code in one of two shapes:

• SARS-aligned rates – YYYYMMDD-<suffix>. YYYYMMDD is the rate's effective start date (e.g. 20180401 for the post-VAT-hike 15% era) or its end date for historical rates (e.g. 20180331 for the legacy 14% rates). <suffix> is the SARS VAT201 field number verbatim (1, 1A, 14, 15A, ...).
• Date-independent rates – a bare PascalCase token (NotRegisteredVendor, OutOfScope, ZeroRatedPurchase) for non-VAT201 rows that have no SARS box.

The complete catalogue lives in numbers_value_added_tax_rates. Contact your Mosaic administrator if you need a code that is not in the table above.

Response

202 Accepted with a Location header.

{
  "spending_method_identifier": "019f1234-5678-7abc-9def-0123456789ab",
  "schema_version": "1.0.0",
  "type": "supplier-bill",
  "status": "draft",
  "_links": {
    "self": "/v1/numbers-spending-methods/019f1234-5678-7abc-9def-0123456789ab"
  }
}

Warnings

When a bill is ingested but something looks off, the response includes a warnings array. The draft transaction is still created and surfaces in the Hub UI for review.

{
  "spending_method_identifier": "019f1234-5678-7abc-9def-0123456789ab",
  "schema_version": "1.0.0",
  "type": "supplier-bill",
  "status": "draft",
  "warnings": [
    {
      "code": "vat-rate-out-of-window",
      "message": "Invoice date 2018-02-15 falls outside the effective window of VAT rate 20180401-15; the bill was ingested but the transaction date and VAT period are inconsistent.",
      "line_index": 0,
      "vat201_rate_code": "20180401-15"
    }
  ],
  "_links": {
    "self": "/v1/numbers-spending-methods/019f1234-5678-7abc-9def-0123456789ab"
  }
}

End-to-end cURL example

# Assumes you have already computed Authorization, X-Mosaic-Timestamp and X-Mosaic-Nonce
# using the canonical string described in /mosaic-hub-developer-authentication.php

curl -i -X POST https://api.mosaic.co.za/v1/numbers-spending-methods \
  -H "Authorization: Mosaic-HMAC-SHA256 key-id=$KEY_ID,signature=$SIGNATURE" \
  -H "X-Mosaic-Timestamp: $TIMESTAMP" \
  -H "X-Mosaic-Nonce: $NONCE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "spending-method=@bill.json;type=application/json" \
  -F "attachment=@bill.pdf;type=application/pdf"

Idempotency

The Idempotency-Key header is mandatory. The server remembers the request hash (JSON + attachment) for at least 24 hours:

• Same key, same payload → the original 202 response is replayed verbatim with an additional Idempotent-Replay: true header. No new draft transaction is created.
• Same key, different payload → 422 idempotency-key-conflict.

Always generate a fresh UUID v7 per logical request, persist it locally before calling the API, and reuse it on retries.

Errors