List & Retrieve

Unified invoice list

GET /v1/invoices

The single canonical place to see all invoices for your organization — house-issued and SAT-extracted, in one list. Every row carries a source field so you know where it came from.

curl -u "$API_KEY:" \
  "https://api.example.com/v1/invoices?source=house&type=I&per_page=20"

{
  "data": [
    {
      "id":                "01936f7a-4b2c-7e8d-9f0a-1b2c3d4e5f6a",
      "source":            "house",
      "uuid":              "B4E2CBF2-E0E3-4AEF-8F97-9C6E77B29C1B",
      "type":              "I",
      "status":            "stamped",
      "total":             6960.00,
      "currency":          "MXN",
      "date":              "2026-07-01T18:00:00+00:00",
      "issuer_name":       "MI EMPRESA SA DE CV",
      "issuer_tax_id":     "XEXX010101000",
      "receiver_name":     "ESCUELA KEMPER URGATE",
      "receiver_tax_id":   "EKU9003173C9",
      "entity_id":         "9b1c0e2a-4d3f-4a1b-8c2d-1e2f3a4b5c6d",
      "has_xml":           true,
      "has_pdf":           true,
      "confirmed_by_sat":  true
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page":    3,
    "per_page":     20,
    "total":        54
  }
}

Deduplication

A CFDI issued here and later downloaded from the SAT would otherwise appear twice. The unified list deduplicates by UUID: if the same UUID exists in both sources, only the house row is returned (source: house has priority over source: extraction). The confirmed_by_sat flag on the house row indicates that SAT extraction data also exists for it.

Query parameters

Response field reference

Per-entity lists

To list invoices scoped to a single entity:

• House-issued: GET /v1/entities/{entity_id}/issued-invoices
• SAT-extracted: GET /v1/entities/{entity_id}/invoices — paginated (500 per page), rich filter set (see Extraction detail)

Both support per_page.

Get a single issued invoice

GET /v1/issued-invoices/{id}

Returns one issued invoice belonging to your organization. Returns 404 if the invoice does not exist or belongs to a different organization.

Download XML and PDF

Stamped XML

GET /v1/issued-invoices/{id}/xml

Returns the stamped CFDI 4.0 XML as application/xml. This is the legally valid document bearing the SAT's digital seal and UUID.

Returns 404 if the XML is not yet available (e.g. stamping failed or the file has not been archived).

Printable PDF

GET /v1/issued-invoices/{id}/pdf

Returns the printable PDF as application/pdf.

Returns 404 if the PDF is not available. A 404 here does not mean the invoice failed to stamp — check xml.available and status on the invoice record.

Extraction detail

For invoices downloaded from the SAT (source: extraction), use the per-entity endpoint for full detail:

• List: GET /v1/entities/{entity_id}/invoices — paginated (500 per page), rich filter set below.
• Get one: GET /v1/invoices/{id} — full detail including line_items, payments, relations.
• Download CFDI: GET /v1/invoices/{id}/cfdi — send Accept: application/xml for XML, omit for PDF.

Extraction list filters

PPD financial aggregates (extraction invoices, type I)

The following fields are populated on type I + PPD extraction invoices, updated each time a related payment complement or credit note is extracted:

credited_amount is empty (not zero) when the amount cannot be determined reliably: the credit note relates to more than one invoice, currencies differ, or all linked credit notes are cancelled.

Related pages

• Issue an invoice — POST /v1/issued-invoices
• Cancel an invoice — DELETE /v1/issued-invoices/{id}
• Reference: catalogs & statuses — extraction status dimensions