Buyer district (KSA-4) empty, or longer than the limit

What does this mean?

What the Authority's live API returns, verbatim: [BR-KSA-F-06-C28] - Field character limits for the Buyer Address - District field (KSA-4) have not been met. The minimum limit is 1 character and the maximum limit is 127 characters. It matches the SDK extract printed at the top of this page.

The field is KSA-4 — cbc:CitySubdivisionName inside cac:AccountingCustomerParty/cac:Party/cac:PostalAddress. It is the one element of the six that has no counterpart in most foreign address models, which is why it arrives empty far more often than any of the others.

The rule measures length: fewer than one character fails, more than 127 fails. It does not ask about presence — that is the question BR-KSA-63 asks, counting the six elements of a Saudi buyer address and naming the district among them.

We saw this code come back on a live run, on a standard invoice whose buyer address held a street, a city and a postal code and was short of the district and the building number — alongside BR-KSA-63. So an absent field was enough to fail the length rule; it is not only a field written empty. And on another invoice the same day, whose buyer address was empty throughout, the response carried BR-KSA-63, BR-KSA-10 and the street and city length rules — but not this one. The extract we work from gives us each rule's message and severity, not the test behind it, so we cannot tell you why the two runs parted. What we can tell you is that absence alone is enough to bring this warning back, so do not build on removing the element to silence it.

It is a warning: the Authority clears the invoice and the note returns with the acceptance, so no sale waits on a district the buyer sometimes does not know themselves. But the document stays short of the district in your records and in theirs, it is the kind of gap a buyer's accounts team or whoever reviews your books may ask about, and the warning returns on every invoice to that customer while their record is unchanged.

Why does it happen?

Ordered from the most common to the least — your cause is most likely the first or the second.

• A template that prints <cbc:CitySubdivisionName> on every invoice, so it comes out empty whenever the column is blank — and it is the emptiest column in any customer database.
• Your address model has no district field at all: a foreign address knows a street, a city, a state and a postal code, and knows no district. The element is written because the Saudi standard asks for it, and there is no value to put in it.
• District confused with administrative region in the mapping: some platforms call the region field province or state and leave it empty on Saudi addresses, so binding it to the district empties the district on every invoice.
• Different names on the two sides of an integration — district here, subdivision or neighborhood there — so the fields never match and the element keeps being written with no value.
• A shipping address carried across from an online store as it stands: a free-form delivery address rather than a national one, where the district is part of a line instead of a field of its own.
• The maximum from the other side, which is rare: a whole set of directions typed into the district field — behind the mosque, next to the such-and-such — running past 127 characters.

How to fix it

4 steps, then send the invoice again.

1. 1
   Never fill the district with the city, or with a dash

   This is the most important sentence on the page. The city name in the district field satisfies one character and silences the code, and it leaves a district that is not the buyer's on a signed tax document — a document that says Riyadh where it should say Al Malqa is wrong in a way a reader notices. A dash, a dot, zeros and the words not available are all the same move: values that pass the length rule and mislead about the buyer. The recorded warning is more honest than any of them.

2. 2
   Take the district from the national address, its only source

   The district cannot be derived from the rest of the address, and it cannot be derived from the postal code. Its source is the national address: ask the customer for their national short address — four letters then four digits — or their national address certificate, where the district is written beside the street and the building number. The six buyer fields and where a customer finds them are set out in the tax invoice requirements checklist.

3. 3
   Add a district field rather than borrowing one

   If your address model is a foreign one, do not bind the district to the state or region field because it is the nearest thing available. Add a column of its own, map it to KSA-4 alone, and have the XML generator write the element when that column has a value and not before. A borrowed field fills wrongly today and makes the correction harder tomorrow.

4. 4
   Correct the customer record — the issued invoice is not reissued

   The invoice that carried the warning was cleared and does not need reissuing to stand. Correct the district in the customer record and their next invoices go out clean. In the same pass, check its neighbours: the street under BR-KSA-F-06-C23, the city under BR-KSA-F-06-C25, and the six elements together under BR-KSA-63.

This code does not block acceptance, so the invoice you have is compliant. Correct the data so the warnings disappear from future invoices.

Frequently asked questions