CFDI addenda: what it is and how to add one

Your CFDI (Mexico's electronic invoice) is stamped (stamping: the certification by a SAT-authorized provider that makes a CFDI valid) and valid with the SAT (Mexico's tax authority, Servicio de Administración Tributaria), and Walmart still won't pay you. The supplier portal sends the invoice back with a generic "incomplete document" message, and nobody at the call center can tell you why. Stamping went through fine. The problem is the missing CFDI addenda (commercial data a recipient asks for, outside the SAT's rules; not a complement). It's a requirement from your customer, and the SAT doesn't define what goes in one.

This happens to almost every retail-chain supplier the first time. The invoice is flawless for tax purposes and commercially useless. This post explains what an addenda is, why it isn't a complement (complemento, an XML extension the SAT defines for specific operations), and why past a certain volume you can't build it by hand.

What is a CFDI addenda

An addenda is a block of commercial data that the recipient of a CFDI requires inside the XML before it can process your payment. The SAT doesn't define its format and the PAC (Proveedor Autorizado de Certificación, a SAT-authorized provider that stamps CFDIs) doesn't validate it: each company publishes its own format. It lives in the <cfdi:Addenda> node, outside the digital seal (the issuer's signature over the CFDI, made with its CSD), and it only matters to whoever is going to pay you.

That last sentence is the key. The addenda has nothing to do with your tax obligations. The SAT doesn't ask for it, doesn't review it, and doesn't care about it. The one asking for it is your customer's accounts payable team, almost always a retail chain or a large company, which needs to match your invoice to its purchase order before it approves the payment in its internal system.

Addenda vs complement: they aren't the same thing

This is where almost everyone gets confused, experienced development teams included. A complement, such as payroll, payments, Comercio Exterior (the CFDI foreign trade complement for exports), or Carta Porte (the CFDI complement that documents the transport of goods in Mexico), is defined by the SAT: it has a published XSD, the PAC validates it at stamping, and it's part of the digital seal. An addenda meets none of those four conditions.

The practical consequence of that table: you catch a bad complement right away, because stamping fails. You catch a bad addenda days later, when the customer's portal rejects the invoice or, worse, when the payment never shows up and nobody told you. A tax error is loud. An addenda error is silent, and that's why it costs more.

One technical detail is worth pinning down from the start. You add the addenda after stamping, not before. The <cfdi:Addenda> node goes at the end of the CFDI, after the TimbreFiscalDigital, precisely because it isn't part of the original string (cadena original, the sequence of CFDI data that the digital seal signs) or of the SAT seal (the seal inside the digital tax stamp that certifies the CFDI). If you put it in before stamping, you depend on how that PAC handles it: it may ignore the node or reject it. The correct XML order looks like this:

<cfdi:Comprobante Version="4.0" ...>
  <cfdi:Emisor .../>
  <cfdi:Receptor .../>
  <cfdi:Conceptos> ... </cfdi:Conceptos>
  <cfdi:Complemento>
    <tfd:TimbreFiscalDigital .../>   <!-- The PAC adds it at stamping -->
  </cfdi:Complemento>
  <cfdi:Addenda>
    <!-- Free-form content, in the format the recipient defines.
         The SAT doesn't validate anything that goes in here. -->
  </cfdi:Addenda>
</cfdi:Comprobante>

What goes inside <cfdi:Addenda> has no SAT rules. It has your customer's rules, and that's the real problem.

Which retailers require an addenda, and why each one is different

There's no such thing as "the addenda." Mexico has dozens of retailer addenda formats, one for each chain that asks for one, and they don't look alike. Walmart (which brings Bodega Aurrerá and Sam's Club along with it), Liverpool, Soriana, Chedraui, HEB, La Comer, Costco, Home Depot, Coppel, and Cinépolis each have their own schema, their own list of required fields, and their own receiving portal. What Liverpool calls the supplier number, Soriana calls something else and puts in a different node.

The data almost all of them ask for revolves around the same few things: the supplier number the chain assigned you, the purchase order number, the delivery or delivery note number, and sometimes the order number from the EDI system. But the exact format, the field names, the XML namespace, and the validations change completely from one chain to the next. A Walmart addenda won't work for Liverpool. Not even close.

This matters for an architecture decision. If you invoice one large customer, you can study its specification once and be done. If you invoice fifteen different chains, keeping fifteen addenda generators in sync with the changes each chain publishes on its own schedule is a project in itself. Each retailer's addenda specification usually lives in its supplier portal, not in a public standard, and the chain changes it whenever it decides to.

How to add an addenda to a CFDI

The correct flow has an order you can't change. You stamp first, add the addenda after, and deliver the complete XML through the channel the customer requires (its portal, its EDI, or an email to a specific address).

End to end, the life cycle of an invoice with an addenda looks like this:

The retry loop between the portal's rejection and the addenda fix is where the time goes. Each chain rejects for different reasons and with different messages, and that cycle repeats for every new customer you add.

Common mistakes when issuing an addenda

How to handle addendas programmatically

At low volume and with a single customer, you can handle an addenda by studying its specification and building the XML by hand once. The problem shows up when you invoice several chains: each with its own schema, portal, and changes, and all of them holding up payment if something goes wrong. At that point, maintaining your own generators stops being code and becomes a permanent support function.

Fiscalapi handles the fiscal side: it stamps the CFDI through a PAC and returns the stamped XML, which you can also download later by the invoice's ID. The addenda stays on your side. Fiscalapi doesn't build addendas or track retailer specifications, so your system adds the Addenda node to that XML, in each chain's format, after stamping. Issuing and stamping the base CFDI and getting its XML are covered in the Fiscalapi documentation, and the official SDKs for .NET, Node.js, Python, PHP, and Java cover the same flow. The examples on GitHub show the issue-and-stamp flow end to end. If you're still working out basic stamping, the details are in the CFDI stamping guide.

Frequently asked questions about the addenda

If you're about to start selling to your first retail chain, assume the first invoice will bounce and test with a small amount before the full batch. The addenda is one of those requirements nobody explains until a payment has already been held up, and the stamping process is the only step in all of this that the SAT does control.