CBS Index Linkage Automation for Contracts: Updating Without Rewriting History

Israel's Central Bureau of Statistics publishes price indices through a public interface returning an index catalogue, index values by code, and a linkage calculator. The engineering problem is not fetching the number but storing it: a charge already issued has to stay as it was, even after the index is revised or the base is replaced.

What the CBS interface returns

That table is all you need to see why this looks simple and then is not. The first three operations are enough to compute with, and the fourth is tempting enough to skip computing yourself - right up until somebody asks why April's charge came out the way it did.

Why does a stored index number stop matching a year later?

Because the stated value depends on the base. The CBS publishes the index relative to a base - for example the 2024 average - and replaces the base periodically. At that moment the same point in history acquires a different number without anything economic having changed.

The interface handles this with a chaining coefficient. In the test we ran, July 2026 came back as 105.1 on the 2024-average base, and the same month was also presented on older bases with chaining coefficients bridging between them. The same mechanism appears in the calculator response, which returns a coefficient alongside the source and target index values.

So a single field called base_index is a future bug. What you store has to be a triple:

• The index value.
• The description of the base it refers to.
• The month it belongs to.

The schema that permits recomputation without rewriting

One rule matters: the charge is a fact, the linkage is a calculation. A charge that went out is stored with everything used to compute it, and is never updated when a new index arrives.

1. On the contract, store the base index - value, base and month - as fixed at the start of the engagement.
2. In an index table, store every publication as a row: index code, month, value, base description, and when it was fetched.
3. For each billing period, create a row snapshotting the period index, the base index, the coefficient used and the result.
4. A correction is not an update to an existing row but a new correction row referencing the original and explaining the difference.
5. Recomputation is permitted only for periods not yet closed, and always produces a new version instead of overwriting.

That difference in approach is the difference between a system you can audit and one where "how much did we charge in March and why" is answered by guesswork. The same pattern of storing a value on the row rather than recomputing it appears in contract renewal reminder control.

What does the audit trail of an indexed charge need to contain?

The question actually asked is never "what is the index" but "why did this line come out at this amount". A complete answer needs five values on the row itself, not in a separate log file:

• The base amount before linkage.
• The base index, with its base description and month.
• The period index, with its base description and month.
• The coefficient or ratio actually used.
• Who ran the calculation and when.

It is worth being equally explicit about what does not go on the row. Do not store an index name as free text, because names change while codes stay stable. Do not store only a computed percentage change, because you cannot get back to the values behind it. And do not store "the latest index" as a live reference into a table, because it will move next month and take last year's explanation with it.

With those five on the row, any charge can be reconstructed without reaching the external interface and without depending on the index not having changed since. The cash flow that follows from it connects to the collection process described in automating invoices and payment reminders.

Measurable traps in the interface itself

• The User-Agent header. The CBS documentation states this header is mandatory on a request. In the test we ran, a request sent with Mozilla/5.0 had its connection reset, while curl/8.6.0, python-requests/2.32 and a request with no header at all returned 200.
• XML only. The documentation notes that some principal-index endpoints currently support XML only. In our test, sending format=json to one of them still returned XML.
• Calculator date format. The documentation gives month-day-year or year-month-day. In our test 08-15-2020 worked while 15-08-2020 returned an error.
• Provisional values. The CBS notes that for the housing price index the last three values are provisional and may be revised, and that linking to a period where the index is still provisional is not recommended.
• Publication lag. A given month's value does not exist during that month. A system computing a charge at the start of a month has to know in advance which index will be available at that moment, rather than discovering it at run time.
• Matching on an index name. The same index appears under different wordings across sources, so requests are made by code. An index name stored as text on your side is a permanent source of quiet error.

What to have ready before building

• The list of contracts that are actually linked, with each one's base index as recorded in the agreement.
• A decision on which index applies to each contract type, by code rather than by name.
• Somewhere to store an index publication as a historical row rather than a single value that gets overwritten.
• A defined behaviour for the required index not yet being published on the run date.
• Who approves recomputing a closed period, and where that is recorded.

Sources

• Price indices through the API - Israel Central Bureau of Statistics
• Index subject catalogue - Israel Central Bureau of Statistics
• Consumer price index data, code 120010