This guide goes field by field and rule by rule, with what the tax authority actually checks before accepting a document. That is why it distinguishes between what the rule says, what the service does and what circulates without any document backing it. The three get confused often, and they have different consequences.
What version 4.4 is and when it took effect
It is the format Costa Rican electronic documents are built with today. It was established by resolution MH-DGT-RES-0027-2024, and its annexes — the document that says, field by field, how each type is assembled — have been updated since.
An electronic document is not a nicely laid-out PDF: it is an XML file with an exact structure, digitally signed, transmitted to the tax authority, which replies accepting or rejecting it. The PDF you hand your customer is a representation of that file, not the fiscal document.
Why a rejection hurts more than it looks
The annex defines dozens of validations, and they do not all carry the same weight: some are warnings and many others end in the document will be rejected. That difference matters for one very concrete reason:
From which follows the most important practical rule in all of this: whatever can be validated before transmitting, gets validated before transmitting. Software that lets you issue and finds out it was wrong when the tax authority answers is spending your numbers for you.
What changed from version 4.3
The annex's version history puts it plainly: 4.4 has been in force since 1 September 2025, and from that date 4.3 is repealed.
The rest are structural changes. These are the ones that actually change the work:
| What changed | Why it matters |
|---|---|
| The payment method moved | It left the header and moved to the document summary. Software that was not updated still puts it where it used to be. |
| The credit term is now a number | It became a five-digit integer expressed in days. It used to accept free text, and all sorts came through. |
| Three new sale conditions | Sale of used goods to a non-taxpayer, operating lease and finance lease. They used to be forced into “other”. |
| Code 11 was rewritten | It is now “payment of a credit sale under the 90-day VAT rule”, with article 27 of the VAT Act behind it. |
| Recipient identification is mandatory on exports | On an export invoice it stopped being optional, and the field grew to twenty characters. |
| “Non-domiciled foreigner” was narrowed | That identification type is now only accepted on a purchase invoice, and requires a reference document with code 16 alongside it. |
| The product code is mandatory on notes | Credit and debit notes now carry it too, with exceptions. A frequent cause of rejection when migrating. |
| Tariff heading on goods exports | If the CABYS code is a good, the tariff heading is mandatory on the export invoice. |
What was adjusted in April 2026
The annex did not freeze when it came into force: it has a change log, and the latest entry is from 22 April 2026. One change there has barely been reported and breaks software silently:
Three smaller items entered the same log: an exception in the telephone field for special numbers such as 911, more detail in the refunded-VAT field, and new codes in the reference document notes.
The seven document types, one by one
Version 4.4 defines seven different documents, and each covers a situation the others do not. Many invoicing products on the market issue only the first two; if you have operations of the other five kinds, that is not enough.
-
1 · Electronic invoice
A sale to a customer identified by their tax number. It is the document that supports the recipient's expense and input VAT.
-
2 · Electronic ticket
A sale to a final consumer who does not ask for an invoice. A ticket does not support input VAT for the buyer: if your customer needs it for their books, you have to issue an invoice.
-
3 · Credit note
Cancels or reduces a document already issued: a return, a later discount, a mistake. An electronic invoice is never “deleted”; a credit note corrects it.
-
4 · Debit note
The opposite: it increases the amount of a document already issued, when you invoiced too little.
-
5 · Purchase invoice
Issued by the buyer, not the seller. It covers cases where the supplier cannot issue a Costa Rican electronic document, typically because they are abroad or are not a registered taxpayer. It carries the reverse charge with it: the tax is declared by the buyer. It is the document anyone paying commissions to Airbnb, Booking or any foreign platform needs. How it applies to a rental.
-
6 · Export invoice
A sale abroad, with its currency and exchange rate. It is declared separately from local sales, and a credit note on an export counts as an export, not a local sale.
-
7 · Electronic payment receipt
The document for collecting on a credit invoice. It is by some distance the most ignored of the seven and the one that does the most damage when missing: it decides which month the VAT on a credit sale is declared in.
The 50-digit key and the sequence number
Every electronic document is identified by a 50-digit numeric key built from the country, the date, the issuer's identification, the sequence number, the situation and a security code. It is not a number the software assigns as it pleases: it is assembled by a rule, and that key identifies the document uniquely across the country.
Which has a practical consequence worth demanding of any software you hire: a document's identifier should be its key, not an internal number. Software that invents its own identifiers is software that is hard to leave, and hard to reconcile with your accounts.
| Positions | What it is |
|---|---|
| 1 – 3 | Country code. Costa Rica is 506 |
| 4 – 9 | Day, month and year of issue |
| 10 – 21 | Issuer identification, padded with leading zeros |
| 22 – 41 | The sequence: branch, terminal, document type and running number |
| 42 | Situation: normal, contingency or offline |
| 43 – 50 | Security code, generated by the issuer |
The sequence number is the other piece. It is consecutive and cannot skip or repeat. That is why, when changing invoicing software, the first thing to settle is continuing the numbering where the previous one left off.
The issue date has three rules, not one
It looks like the most innocent field on the document and it is among the ones that cause the most rejections, because almost everyone knows only the first of its rules. The annex asks for all three at once:
- Neither later nor earlier than generation. It is not just that it cannot be in the future: it cannot be in the past either. Invoicing on Monday something delivered on Friday carries Monday's date.
- An earlier date fits in one case only. The annex admits it solely in documents issued offline, which is one of the three possible situations.
- It has to match the date inside the key. This is the one that gets away. The key carries the day, month and year in positions 4 to 9; if the document is assembled near midnight, or the software takes the hour from one time zone and the date from another, the two separate by a day and the tax authority rejects it.
Normal, contingency and offline
Position 42 of the key says which situation the document was issued in, and it is not an administrative detail: it decides which dates are admitted and what is expected of you afterwards.
| Situation | When | What it implies |
|---|---|---|
| 1 · Normal | The usual: there is a connection and the tax authority answers | The issue date is today |
| 2 · Contingency | There is internet, but the tax authority's service is not responding | You issue anyway and transmit when the service returns |
| 3 · Offline | There is no connection at your end | The only one that admits an issue date earlier than validation |
The practical consequence: if your software goes down and you keep selling, the document does not go unissued. What you cannot do is issue it later with yesterday's date marked as normal, because the annex does not admit that combination.
The sale condition, and why it rejects so much
It is a two-digit field almost nobody looks at, and the annex gives it cross-cutting rules: some codes are valid only in one document type, and some drag another mandatory field with them. These are the four that cause the most rejections.
- The payment receipt admits only two. Codes 09 — payment for services rendered to the State — and 11 — payment of a credit sale under the 90-day VAT rule. Any other is a rejection.
- Non-nationalised goods, invoice only. Code 12 is not valid on a ticket or a note.
- Credit drags the term with it. If the condition is 02 (credit) or 10 (credit sale under the 90-day VAT rule), the term becomes mandatory, in days and greater than zero. Since 4.4 it is an integer, not text: “30 days” is no longer written, you write 30.
- “Other” requires an explanation. Code 99 requires filling in the detail with a minimum of five characters. Leaving it empty, or writing “n/a”, rejects.
That code 10 deserves a stop, because it is money: a credit sale under the 90-day VAT rule is what lets you declare the VAT when you collect and not when you invoice, resting on article 27 of the VAT Act. It is the reason the electronic payment receipt exists.
What you need to start issuing
Two things, both obtained from TRIBU-CR: the signing certificate — the file your documents are signed with, plus its PIN — and the API credentials, the username and password your software uses to talk to the tax authority.
They are generated at ovitribucr.hacienda.go.cr, in the Tico Factura section. The old ATV portal was replaced by TRIBU-CR in October 2025, so any instructions you find online pointing at ATV are out of date.
What happens after you press “issue”
Your software signs the XML and sends it. From there the document passes through five possible states, and only three are final:
| State | What it means |
|---|---|
| Received | It arrived. Not reviewed yet |
| Processing | Being validated. You have to ask again |
| Accepted | Final. This is the answer to keep |
| Rejected | Final. The number is spent |
| Error | Final, and the worst handled: it is not in the official guide, but it is in the service |
That last one explains a symptom many people know: a document stuck on “sent” forever. Software that only contemplates the four documented states waits for an answer that already arrived.
Why you sometimes get “unknown error”
Worth being honest about something nobody mentions: the official documentation and the real service do not say exactly the same thing. They are small differences, and each one is paid for with an error that reaches the user unexplained:
- The documentation says a correct submission answers with one code and the service sometimes answers with another. Software expecting only the documented one treats a successful submission as failed, and you end up with a duplicate or nothing at all.
- When a document is rejected on format, the reason does not travel where you look for it: it comes in a response header, not the body. Software reading only the body shows you “error 400” and stops. That is where the unhelpful “unknown error” comes from.
- The fields in the status query are spelled two different ways depending which part of the documentation you read, and both have to be accepted.
This is not a criticism of the tax authority: these are large services that evolve faster than their manuals. But it explains why two programs facing the same rejection tell you different things, and why it is worth asking whether yours was built against the real service or only against the PDF.
Receiving is not optional: the recipient message
Issuing is half the work. The other half is answering the documents your suppliers issue to you, with what is called a recipient message: acceptance, rejection or partial acceptance.
All electronic documents and associated documents issued by the electronic issuer-recipient must have the corresponding acceptance message as support for the validation; otherwise they cannot be used to support input tax credits or deductible expenses, nor affect self-assessed tax returns.
Electronic Documents Regulation, article 21Read it slowly, because it says more than it appears: a purchase with no acceptance message is of no use to you. Not for input VAT, not as a deductible expense. Even if you paid it, even if you have the XML saved.
Six errors that end in rejection
-
The CABYS code does not match the VAT rate
The tax authority cross-checks the two. Putting 13 % VAT on a basic-basket code is a rejection. If the catalogue says a different rate, there is a reason: check before forcing it.
-
The CABYS code does not exist in the current catalogue
The catalogue changes. A code that was valid two years ago may not be valid today. The software should check it when you create the product, when there is time to fix it, and not at the moment of invoicing.
-
Using a rate code reserved for notes on an invoice
Some rate codes are reserved by the annex for credit and debit notes. Using them on an invoice or a ticket is a straight rejection.
-
An issue date the rule does not admit
It cannot be earlier either, except offline. And it has to match the date inside the key — which is where the real error sneaks in, near midnight or across time zones.
-
Voiding something the tax authority already rejected
A rejected document is not voided: it never existed for tax purposes. Issuing a credit note against it is a conceptual error that also bounces.
-
Quantities or amounts out of range
Negative quantities, negative prices, amounts larger than the field. A screen that validates nothing lets through things the eye does not catch: a quantity of −3 and a price of −5,000 give a perfectly normal positive total.
What you have to keep, and for how long
Five years, under article 22 of the regulation, and both the documents you issued and the ones you received, together with their associated documents.
What has to be kept is the XML with the tax authority's signed response, not the PDF. The PDF is the representation; the XML is the document. If software only lets you download PDFs, it is not letting you comply.
How to choose invoicing software
With all of the above, the useful questions to ask any provider are these:
- Does it issue all seven types? Especially the payment receipt and the purchase invoice.
- Does it receive and answer purchases? Does it warn you before the deadline passes?
- Does it validate CABYS against the catalogue? When — on creating the product, or on invoicing?
- Is there a test environment? Can you see on screen which one you are in?
- Can I take my data with me? XML with the tax authority's response, not just PDF.
- Will it continue my numbering? If you are coming from another product, this is not negotiable.
The key and the sequence, built by the rule
They are the first two things that break when this is done by hand. Ticuenta assembles them from the annex's rule — nobody types them.
See how it worksAbout this guide. Everything here comes from resolution MH-DGT-RES-0027-2024 and its annexes, including the change log of 22 April 2026; the recipient message quotation, from article 21 of the Electronic Documents Regulation; the five-year retention, from its article 22. The differences between the documentation and the real service are observations, and they are labelled as such.
Verified as of 24 September 2026. Tax rules change. This is information, not tax advice — confirm the current version before applying it to a real case.
Sources: Ministry of Finance Current legal texts (Sinalevi)