Buyer city (BT-52) empty, or longer than the limit

What does this mean?

What the Authority's live API returns, verbatim: [BR-KSA-F-06-C25] - Field character limits for the Buyer Address - City field (BT-52) have not been met. The minimum limit is 1 character and the maximum limit is 127 characters. That text matches the SDK extract printed at the top of this page word for word — unlike the street rule BR-KSA-F-06-C23, where the two disagree on the maximum.

The field is BT-52 — cbc:CityName inside cac:AccountingCustomerParty/cac:Party/cac:PostalAddress. It is a length rule: it counts characters and asks nothing about presence. Fewer than one fails, more than 127 fails.

Zero characters reaches the validator by two roads: an element written empty, such as <cbc:CityName/>, and an element that was never written. We saw the warning come back on a standard invoice whose buyer address was empty throughout, generated by a system that does not write empty address elements at all — so do not assume that leaving the element out silences a length rule.

One thing sets this field apart from the street and the district: a city is not hard information to obtain. Every buyer knows their city, every purchase form asks for it, every shipping address carries it. So when the field arrives empty, nine times in ten the fact is not missing — it simply did not arrive: a column that was never matched during an import, a web form field named town while the mapping reads city, or a select whose first, empty option was submitted. Look in the mapping before you look in the customer record.

Three rules speak about the city from three angles and return together in one response: BR-KSA-10 asks for a street, a city and a country code on a tax invoice and its notes, BR-KSA-63 asks for the six elements of a Saudi buyer address, and this one measures the length. A real city in its own field settles all three.

It is a warning: the invoice is cleared and the note recorded with it, so nothing is held up. But a tax invoice with no buyer city is an incomplete document in the buyer's books before it is one in yours, their accounts team may ask about it, 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 city select whose first option is Choose a city with an empty value, submitted as it stands and written out as an element with nothing in it.
• An import from a spreadsheet whose column is headed Town, Region or Province, never matched to the city column, leaving the field empty.
• An address taken from a checkout that does not require a city — common in stores that deliver by map pin, where coordinates are enough for the driver and not enough for a tax document.
• City and district swapped in the mapping, so the district field holds the city and the city field is left empty. This happens often when the foreign system names the two fields city and district in a different order from your own form.
• An administrative region written in the city field and then cleared during a clean-up: Eastern Province is not a city, and whoever removed it put nothing in its place.
• The maximum from the other side — rare, but it happens: a whole address line, or a city name written in two languages with a description between them, in a field limited to 127 characters.

How to fix it

4 steps, then send the invoice again.

1. 1
   Inspect the mapping before you inspect the customer

   Take one invoice that carried the warning and look at the XML that was sent. If <cbc:CityName/> is there and empty, the fault is in the serialisation; if it is absent, the fault is at the source. Then check the customer record in your own system: if the city is present there and the field still arrives empty, the problem is the match between your column and BT-52 — and that is fixed once, for every invoice that follows.

2. 2
   A city is a city — not a region, and not a district

   Write the city name into BT-52 as the national address gives it: Riyadh, Jeddah, Khobar. An administrative region is not a city, and the district has a field of its own (KSA-4) with a rule of its own, BR-KSA-F-06-C28. Moving a value from one to the other so that both fields are full makes the document state something untrue about the buyer.

3. 3
   Turn an empty value into an absent one

   In the mapping: convert the empty string, the Choose placeholder and the whitespace-only value into absence before the payload is built, not after. An empty element inside a signed document serves nobody; and do not pad it with a dash or a dot to satisfy the one-character minimum, because that is a value that passes the rule and misleads whoever reads the invoice.

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

   The document that carried the warning was cleared and does not need reissuing. Correct the city in the customer record and their next invoices go out clean. The quickest route to the rest of the address is the buyer's national short address; the six buyer fields and the rule behind each are set out in the tax invoice requirements checklist.

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