Buyer street (BT-50) empty, or longer than the limit

What does this mean?

What the Authority's live API returns, verbatim: [BR-KSA-F-06-C23] - Field character limits for the Buyer Address - Street field (BT-50) have not been met. The minimum limit is 1 character and the maximum limit is 127 characters.

The message printed at the top of this page comes from the SDK extract we index, and there the maximum for this field is 1000, not 127. The difference is in the maximum alone — the minimum, one character, is the same in both, and it is the one that fails in practice. We have not edited the extract to match what we saw: it is the Authority's own text as shipped in their tooling, and the difference between the two is itself information you are entitled to. Practically: if your street line is long, size it against 127, not 1000.

The field is BT-50 — cbc:StreetName inside cac:AccountingCustomerParty/cac:Party/cac:PostalAddress. The rule does not ask whether the buyer has a street; that is what the presence rules ask. It counts characters: fewer than one fails, more than the maximum fails.

And zero characters reaches the validator by two roads, not one: an element written empty, such as <cbc:StreetName/> from a blank database column, and an element that was never written. Two standard invoices through the live API on the same day showed us which. The document ZATCA Tools generates never writes an empty address element on any path — a part with no value is dropped before the file is built, and a test in the repository holds that — and this warning still came back on the invoice whose buyer address was empty throughout. So do not build on the idea that removing the element silences a length rule: what we saw is that absence fails the minimum exactly as emptiness does.

Two presence rules travel with it in the same response. BR-KSA-10 asks for a street, a city and a country code on a tax invoice and its notes, and BR-KSA-63 asks for six elements once the buyer country code is SA. All three are warnings, and all three speak about the street from a different angle: one says it is not there, this one says its length is zero, the third counts the six. One correction — a real street in its own field — settles all of them.

It is a warning: the Authority clears the invoice and returns the note alongside the acceptance, so no sale waits on a line of address. But accepted is not complete. A tax invoice is a document the buyer keeps and books, their accounts team may send it back because the buyer address on it is short of a part, and the same warning returns on every invoice to that customer for as long as 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 blank street column written out as an element anyway: the template prints <cbc:StreetName> on every invoice, so it comes out as <cbc:StreetName/> when the column holds nothing. This is the most common cause in systems that build XML from a text template instead of element by element.
• A value made of spaces or a newline: the field is not null in your database, and its length after whitespace is normalised is zero.
• The whole address in one field — Address, or Notes — while the street column that has its own element stayed empty: full in the wrong place and empty in the right one.
• The maximum from the other side: a complete address pasted into the street field. The live API answered with a maximum of 127 characters, which a full address line passes easily.
• Customers imported from a spreadsheet that has a street column with empty cells, so an empty string is written where a missing value belonged.
• A mapping that serialises null as an empty string on the way to XML — the default in many serialisation libraries, and invisible until the Authority answers.

How to fix it

4 steps, then send the invoice again.

1. 1
   Write a real street, because nothing else settles the rule

   A length rule takes no trick: an empty element does not pass, and removing it does not guarantee passage either, as the live response showed. What settles it is a value of one character or more that actually describes the buyer's street. Get it from its source: the buyer's national short address — four letters then four digits — or their national address certificate, where the street comes out separated from the rest. The buyer fields and the rule behind each are listed in the tax invoice requirements checklist.

2. 2
   And where you have no value, leaving it out beats emptying it

   An empty element loses twice: it fails the rule, and it leaves an element that means nothing inside a signed document — one a reviewer, or the buyer's accounting system, will read later. An absent element fails only the rule, and the document stays truthful about what you know. So have your XML generator write the element when it has a value and not before, and never pad it with a dash, a dot or the words not available: those satisfy one character while stating something untrue about the buyer, and the warning was the more honest of the two.

3. 3
   Overflow belongs in the additional street, not the street

   If the address line is longer than the limit, split it the way the standard splits it: the street in BT-50, and what comes after it — a unit number, a landmark, a compound name — in the additional street BT-51, that is cbc:AdditionalStreetName, whose maximum is 127 characters under BR-KSA-F-06-C11. Blind truncation at the limit is not a fix: it puts a cut-off address on a tax document.

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

   The invoice that carried the warning was cleared and does not need reissuing to stand. Correct the street in the customer record and their next invoices go out clean. While you are in the address, finish the rest of it: the city under BR-KSA-F-06-C25, the district under BR-KSA-F-06-C28, and the postal code as five digits under BR-KSA-67.

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