Invoices - Clara API

Recommended for all new integrations.

When a Transaction Has an Invoice

If a transaction has invoice:

The hasInvoice field is set to true
You’ll receive a link to download them
URLs are valid for 12 hours

Endpoint Format

GET /v3/transactions/{uuid}/invoicesUse this endpoint to retrieve XML invoice details and metadata associated with a specific transaction.

Example: Getting Invoices for a Transaction

In the following example, we will get the invoice information for the transaction with the UUID “47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1” in Mexico.

cURL Request

cURL

curl -X GET
"https://public-api.mx.clara.com/api/v3/transactions/47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1/invoices" \ 
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sample JSON Response

JSON

{
  "transactionUuid": "47f8ed9e-4d7b-450b-ad6a-f1d83e3ce4e1",
  "invoices": [
    {
      "invoiceId": "54cd6b23-5146-437f-b133-879c432e6776",
      "invoiceNumber": null,
      "taxRegime": "621",
      "issuer": {
        "rfc": "CLARA123XML",
        "businessName": "CLARA"
      },
      "taxReceipts": {
        "cfdi": "G03",
        "paymentMethod": "Q4"
      },
      "tax": {
        "retained": {
          "isr": 0.75,
          "iva": null,
          "ieps": null
        },
        "transferred": {
          "iva": 0.0,
          "ieps": 0.0
        }
      },
      "amount": {
        "total": 400.00,
        "subTotal": 300.00,
        "currency": "MXN"
      },
      "documentDate": "2024-10-01",
      "xmlStatus": "Vigente",
      "xmlCode": "S – Comprobante obtenido satisfactoriamente."
    }
  ]
}

⚠️ The download URL is temporary and will expire 12 hours after generation. Ensure you download and store the file before it expires.ℹ️ Note: The example provided contains mock data and does not reflect real tax calculations or financial details.

Endpoint Reference

`GET /api/v3/transactions/{uuid}/invoices`

Get a transaction by UUIDParameters:

Parameter	In	Type	Required	Description
`uuid`	path	string	✅	Transaction UUID

Response Schema (TransactionInvoiceResponse):

Field	Type	Example
`transactionUuid`	string	`4ea5a94a-2c3c-4601-b623-c30260c21dbc`
`invoices`	array of InvoiceResponse

`GET /api/v3/invoices`

Find all Invoices with optional filtersParameters:

Parameter	In	Type	Description
`page`	query	integer	Zero-based page index (0..N)
`size`	query	integer	The size of the page to be returned
`invoiceNumber`	query	string	Invoice number to filter invoices
`issuerRfc`	query	string	RFC Issuer number to filter invoices
`transactionUuid`	query	string	Transaction UUID to filter invoices
`invoiceId`	query	string	Invoice ID to filter invoices
`documentDateRangeStart`	query	string	Start date for invoice date range filter (must be used together with documentDateRangeEnd)
`documentDateRangeEnd`	query	string	End date for invoice date range filter (must be used together with documentDateRangeStart)

Response Schema (InvoicePageV3):

Field	Type	Example
`totalPages`	integer (int32)
`totalElements`	integer (int64)
`first`	boolean
`last`	boolean
`size`	integer (int32)
`content`	array of InvoiceV3
`number`	integer (int32)
`sort`	object (SortObject)
`pageable`	object (PageableObject)
`numberOfElements`	integer (int32)
`empty`	boolean

sort object (SortObject):

Field	Type	Example
`empty`	boolean
`sorted`	boolean
`unsorted`	boolean

pageable object (PageableObject):

Field	Type	Example
`offset`	integer (int64)
`sort`	object (SortObject)
`paged`	boolean
`pageNumber`	integer (int32)
`pageSize`	integer (int32)
`unpaged`	boolean

What is the Invoices API?

The Invoices API v2 allows you to retrieve invoice records associated with transactions made through Clara. These invoices may be manually uploaded by users or automatically extracted from provider documents such as CFDI XML files (in Mexico).This API is useful for:

Reviewing fiscal documents linked to card transactions
Building tax compliance or expense reconciliation tools
Filtering invoices by multiple criteria such as number, transaction, date, or document ID

Available Endpoints

Operation	Endpoint	Method
Get all invoices with optional filters	`/v2/invoices`	GET

Find all invoices with optional filters

Use this endpoint to fetch a paginated list of invoices, optionally filtered by:

invoiceNumber
transactionUuid
invoiceId
documentDateRangeStart
documentDateRangeEnd

📌 Note: The date range filter is only applied if both documentDateRangeStart and documentDateRangeEnd are present

Endpoint

GET /v2/invoices

Available Query Parameters

Parameter	Type	Required	Description
`invoiceNumber`	string	optional	Filters by invoice number
`transactionUuid`	string	optional	Filters by associated transaction UUID
`invoiceId`	string	optional	Filters by internal invoice ID
`documentDateRangeStart`	string	optional	Start date in ISO format (requires `documentDateRangeEnd`)
`documentDateRangeEnd`	string	optional	End date in ISO format (requires `documentDateRangeStart`)

cURL Request

cURL

curl -X GET \
"https://public-api.mx.clara.com/api/v2/invoices?transactionUuid=txn-123&documentDateRangeStart=2024-06-01&documentDateRangeEnd=2024-06-30" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sample JSON Response

JSON

{
  "content": [
    {
      "uuid": "inv-001",
      "invoiceNumber": "A123",
      "transactionUuid": "txn-123",
      "amount": 400.00,
      "currency": "MXN",
      "documentDate": "2024-06-15",
      "xmlStatus": "Valid",
      "issuer": {
        "rfc": "ABC123456T89",
        "businessName": "Proveedor S.A. de C.V."
      }
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}

💡 Tip: You can combine filters to narrow down invoices by vendor, date, or linked transactions.**⚠️ Note: **This endpoint uses pagination, so be sure to handle page and size parameters or iterate through results if needed.

​When a Transaction Has an Invoice

​Endpoint Format

​Example: Getting Invoices for a Transaction

​cURL Request

​Sample JSON Response

​Endpoint Reference

​GET /api/v3/transactions/{uuid}/invoices

​GET /api/v3/invoices

​What is the Invoices API?

​Available Endpoints

​Find all invoices with optional filters

​Endpoint

​Available Query Parameters

​cURL Request

​Sample JSON Response

When a Transaction Has an Invoice

Endpoint Format

Example: Getting Invoices for a Transaction

cURL Request

Sample JSON Response

Endpoint Reference

`GET /api/v3/transactions/{uuid}/invoices`

`GET /api/v3/invoices`

What is the Invoices API?

Available Endpoints

Find all invoices with optional filters

Endpoint

Available Query Parameters

cURL Request

Sample JSON Response