Reconcile Transactions

This guide walks through the full monthly reconciliation flow: fetching every transaction in a billing period, pulling the matching billing statement for totals verification, tagging transactions with accounting labels, and downloading supporting documents.

Prerequisites

A valid Bearer token and mTLS client certificate. See Authentication.
The billing period you want to reconcile (start and end dates in YYYY-MM-DD format).

Step 1: Fetch all transactions for the period

Use operationDateRangeStart and operationDateRangeEnd to scope the request to a specific billing period. Transactions are paginated — page through all results before moving on.

curl --request GET \
  "https://public-api.mx.clara.com/api/v3/transactions?operationDateRangeStart=2025-04-01&operationDateRangeEnd=2025-04-30&page=0&size=100" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key

Response:

{
  "content": [
    {
      "uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc",
      "type": "PURCHASE",
      "transactionLabel": "AEROMEXICO",
      "status": { "code": "OP", "description": "AUTHORIZED" },
      "amountValue": { "value": 3200.00, "currency": "MXN" },
      "merchant": { "name": "Aeromexico", "category": "TRAVEL" },
      "card": { "lastFourDigits": "3421" },
      "user": { "name": "Ana García", "uuid": "f3a9cb88-894b-4420-aed3-6178cd41721d" },
      "billingStatement": { "uuid": "e4a50134-447f-4c34-b6b6-78cdb43d3fd5" },
      "hasAttachments": { "value": true },
      "hasInvoice": { "value": false }
    }
  ],
  "totalElements": 247,
  "totalPages": 3,
  "size": 100,
  "number": 0
}

Pagination loop

Continue requesting until number equals totalPages - 1, or until a page returns fewer items than size.

page=0 → 100 results
page=1 → 100 results
page=2 → 47 results  ← last page

Available filters:

Filter	Description
`operationDateRangeStart` / `operationDateRangeEnd`	Transaction date range (recommended for reconciliation)
`accountingDateRangeStart` / `accountingDateRangeEnd`	Accounting date range (use if your system books on accounting date)
`lastUpdateDateRangeStart` / `lastUpdateDateRangeEnd`	Catch transactions updated after initial export
`status`	`NOTIFICATION`, `PRE_AUTHORIZED`, `AUTHORIZED`, `REJECTED`, `SYSTEM_TRANSACTION`
`userUuid`	Limit to one cardholder
`cardUuid`	Limit to one card

Pre-authorizations (PRE_AUTHORIZED) may settle as AUTHORIZED up to 2 business days later. For a complete reconciliation, either wait for settlement or run an incremental sync using lastUpdateDateRangeStart.

Step 2: Fetch the billing statement

Get the list of billing statements and find the one whose date range matches your period.

curl --request GET \
  "https://public-api.mx.clara.com/api/v3/billing-statements" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key

Response:

[
  {
    "uuid": "e4a50134-447f-4c34-b6b6-78cdb43d3fd5",
    "statementStartDate": "2025-04-01",
    "statementEndDate": "2025-04-30",
    "currency": "MXN",
    "totalAmount": 184250.00,
    "status": "CLOSED",
    "generatedAt": "2025-05-01T10:00:00Z"
  }
]

Fetch the full statement with its embedded transactions to verify your totals:

curl --request GET \
  "https://public-api.mx.clara.com/api/v3/billing-statements/e4a50134-447f-4c34-b6b6-78cdb43d3fd5" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key

Cross-reference: the sum of amountValue across all AUTHORIZED transactions in your export should equal the statement’s totalAmount.

Step 3: Tag transactions with accounting labels

Labels let you attach GL codes, cost centers, or project IDs to transactions before exporting. Bind them in bulk for efficiency.

curl --request POST \
  "https://public-api.mx.clara.com/api/v3/transactions/labels/bulk" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{
    "transactions": [
      {
        "uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc",
        "labelsUuid": ["label-uuid-travel-001", "label-uuid-cost-center-sales"]
      },
      {
        "uuid": "b1c2d3e4-5678-90ab-cdef-1234567890ab",
        "labelsUuid": ["label-uuid-software-002"]
      }
    ]
  }'

To list available labels, see Labels API.

Step 4: Download supporting documents

For any transaction with hasAttachments.value: true, download the attached receipts.

curl --request GET \
  "https://public-api.mx.clara.com/api/v3/transactions/4ea5a94a-2c3c-4601-b623-c30260c21dbc/documents" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key

Response includes pre-signed S3 URLs valid for 12 hours:

{
  "uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc",
  "attachments": [
    {
      "uuid": "18589896-d30e-4cca-a4e6-716ba323b937",
      "fileName": "receipt.jpg",
      "format": "jpeg",
      "download": {
        "url": "https://...",
        "urlExpiration": "2025-04-30T19:00:00Z"
      }
    }
  ]
}

For Mexico: transactions with hasInvoice.value: true also have a CFDI XML available at GET /api/v3/transactions/{uuid}/invoices.

Export format

Here is a flat row structure suitable for most accounting systems (SAP, NetSuite, QuickBooks):

{
  "transaction_uuid": "4ea5a94a-2c3c-4601-b623-c30260c21dbc",
  "date": "2025-04-15",
  "amount": 3200.00,
  "currency": "MXN",
  "type": "PURCHASE",
  "status": "AUTHORIZED",
  "merchant_name": "Aeromexico",
  "merchant_category": "TRAVEL",
  "cardholder_name": "Ana García",
  "cardholder_uuid": "f3a9cb88-894b-4420-aed3-6178cd41721d",
  "card_last_four": "3421",
  "billing_statement_uuid": "e4a50134-447f-4c34-b6b6-78cdb43d3fd5",
  "labels": ["TRAVEL", "COST_CENTER_SALES"],
  "has_receipt": true
}

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

Reconcile Transactions

Prerequisites

Step 1: Fetch all transactions for the period

Step 2: Fetch the billing statement

Step 3: Tag transactions with accounting labels

Step 4: Download supporting documents

Export format

​Prerequisites

​Step 1: Fetch all transactions for the period

​Pagination loop

​Step 2: Fetch the billing statement

​Step 3: Tag transactions with accounting labels

​Step 4: Download supporting documents

​Export format

​Related

Prerequisites

Step 1: Fetch all transactions for the period

Pagination loop

Step 2: Fetch the billing statement

Step 3: Tag transactions with accounting labels

Step 4: Download supporting documents

Export format

Related