Cash reconciliations

POST https://app.fire.rest/api/v1/adapters/xmart/cash-management/reconciliations
x-api-key: <your_api_key>
Content-Type: application/json

{
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "businessDayDate": "2026-05-06",
  "operatorUid": "op-cashier-123",
  "currency": "BRL",
  "declaredCash": 1250.50,
  "reason": "COUNTING_ERROR",
  "notes": "Short count during evening close — customer overpayment uncounted"
}

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "accountId": "100",
  "vendorId": "v_blueco_br",
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "businessDayDate": "2026-05-06",
  "operatorUid": "op-cashier-123",
  "currency": "BRL",
  "systemCash": 1300.75,
  "declaredCash": 1250.50,
  "discrepancy": -50.25,
  "discrepancyType": "SHORTAGE",
  "authorizationTokenId": null,
  "reportedBy": "apikey:k_ab12cd34",
  "reportedAt": "2026-05-06T16:45:30.000Z",
  "details": {
    "reason": "COUNTING_ERROR",
    "notes": "Short count during evening close — customer overpayment uncounted",
    "post_close": false,
    "authorization": null
  },
  "createdAt": "2026-05-06T16:45:30.000Z",
  "updatedAt": "2026-05-06T16:45:30.000Z"
}

{
  "error": {
    "code": "validation_error",
    "message": "storeId not found in your scope"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "cash-management endpoints require a vendor-scoped API key"
  }
}

POST

api

adapters

xmart

cash-management

reconciliations

POST https://app.fire.rest/api/v1/adapters/xmart/cash-management/reconciliations
x-api-key: <your_api_key>
Content-Type: application/json

{
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "businessDayDate": "2026-05-06",
  "operatorUid": "op-cashier-123",
  "currency": "BRL",
  "declaredCash": 1250.50,
  "reason": "COUNTING_ERROR",
  "notes": "Short count during evening close — customer overpayment uncounted"
}

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "accountId": "100",
  "vendorId": "v_blueco_br",
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "businessDayDate": "2026-05-06",
  "operatorUid": "op-cashier-123",
  "currency": "BRL",
  "systemCash": 1300.75,
  "declaredCash": 1250.50,
  "discrepancy": -50.25,
  "discrepancyType": "SHORTAGE",
  "authorizationTokenId": null,
  "reportedBy": "apikey:k_ab12cd34",
  "reportedAt": "2026-05-06T16:45:30.000Z",
  "details": {
    "reason": "COUNTING_ERROR",
    "notes": "Short count during evening close — customer overpayment uncounted",
    "post_close": false,
    "authorization": null
  },
  "createdAt": "2026-05-06T16:45:30.000Z",
  "updatedAt": "2026-05-06T16:45:30.000Z"
}

{
  "error": {
    "code": "validation_error",
    "message": "storeId not found in your scope"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "cash-management endpoints require a vendor-scoped API key"
  }
}

Partner API. This endpoint is intended for platform integrators. Standard Fire customers do not have direct access — contact your account manager if you need this integration.

Record an end-of-shift or end-of-day cash count for a store and have Fire compare it against what the system says should be on hand. Fire computes the discrepancy (SHORTAGE, OVERAGE, or MATCH), categorises the cause, and stores the result in cash_reconciliations for audit and downstream reporting. This page covers two operations on the same path: POST to record a new reconciliation, GET to list reconciliations for a store/day/operator.

Authentication

string

required

Your Fire API key.

POST — requires the cash-management:write scope.
GET — requires the cash-management:read scope.

The key must be vendor-scoped (account binding required). System-only keys are rejected with 403.

POST — Record a reconciliation

Request body

string

required

UUID of the store the reconciliation belongs to. Must belong to the API key’s account/vendor — Fire returns 400 (with hide-existence behavior — 404-equivalent) otherwise.

string

Business day in YYYY-MM-DD. Defaults to the store’s current operational day. Use this to record a reconciliation for a past day (e.g. retroactive corrections) — Fire flags the result with details.post_close: true if the day is already closed.

string

Operator/cashier ID. Optional. Use it when the reconciliation is for a specific cashier shift; omit when reconciling the whole store-day.

string

required

ISO 4217 code (e.g. BRL, USD, ARS, CLP, COP, VES). Length 3.

number

required

Operator-declared amount of cash on hand. Non-negative decimal. Fire compares this against systemCash (the amount the system thinks should be on hand based on sales and payments) to compute the discrepancy.

string

required

Categorical cause of any discrepancy. One of:

WRONG_CHANGE_GIVEN
COUNTING_ERROR
INCOMPLETE_CUSTOMER_PAYMENT
MINOR_UNIDENTIFIED_DIFFERENCE
THEFT_SUSPECTED
UNRECORDED_PAYMENT
OTHER

Required even when there is no discrepancy — for matched counts, use MINOR_UNIDENTIFIED_DIFFERENCE or OTHER per your operations policy.

string

Free-text. Up to 2000 characters. Use it to capture extra context (operator name, shift notes, etc.).

string

UUID of an authorization token. When present, marks the reconciliation as “requiring/having approval” — typically used for THEFT_SUSPECTED or large SHORTAGE cases that need supervisor sign-off.

POST https://app.fire.rest/api/v1/adapters/xmart/cash-management/reconciliations
x-api-key: <your_api_key>
Content-Type: application/json

{
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "businessDayDate": "2026-05-06",
  "operatorUid": "op-cashier-123",
  "currency": "BRL",
  "declaredCash": 1250.50,
  "reason": "COUNTING_ERROR",
  "notes": "Short count during evening close — customer overpayment uncounted"
}

POST response

string

UUID of the reconciliation row.

string

Account that owns the store.

string | null

Vendor scope, when applicable.

string

Echo of the request.

string

YYYY-MM-DD.

string | null

Echo of the request.

string

ISO 4217.

number

Computed amount of cash the system says should be on hand for this scope (store + day + optional operator). Derived from approved cash payments minus change given, plus opening float.

number

Echo of the request.

number

declaredCash - systemCash. Negative for shortage, positive for overage, zero for match.

string

MATCH (zero), SHORTAGE (declared less than system), or OVERAGE (declared more than system).

string | null

Echo or null.

string

Identity of the principal that recorded this reconciliation. For API-key callers: "apikey:<keyId>".

string

ISO 8601 UTC.

object

Show details

string

Echo of the request.

string | null

Echo of the request.

boolean

true when the reconciliation was recorded after the business day was closed.

object | null

When authorizationTokenId was provided and validated, has { approved_by, approved_at }.

string

ISO 8601 UTC.

string

ISO 8601 UTC.

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "accountId": "100",
  "vendorId": "v_blueco_br",
  "storeId": "550e8400-e29b-41d4-a716-446655440000",
  "businessDayDate": "2026-05-06",
  "operatorUid": "op-cashier-123",
  "currency": "BRL",
  "systemCash": 1300.75,
  "declaredCash": 1250.50,
  "discrepancy": -50.25,
  "discrepancyType": "SHORTAGE",
  "authorizationTokenId": null,
  "reportedBy": "apikey:k_ab12cd34",
  "reportedAt": "2026-05-06T16:45:30.000Z",
  "details": {
    "reason": "COUNTING_ERROR",
    "notes": "Short count during evening close — customer overpayment uncounted",
    "post_close": false,
    "authorization": null
  },
  "createdAt": "2026-05-06T16:45:30.000Z",
  "updatedAt": "2026-05-06T16:45:30.000Z"
}

{
  "error": {
    "code": "validation_error",
    "message": "storeId not found in your scope"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "cash-management endpoints require a vendor-scoped API key"
  }
}

New response fields. Since v2 exists, every reconciliation — including the ones filed here — also returns apiVersion, openingBalance, withdrawalsTotal, sessionExternalId and terminalUid, and details may carry withdrawals and operator_name.On v1 rows apiVersion is 1, withdrawalsTotal is 0 and sessionExternalId is null. These are additions: no existing field changed its value or its meaning.

GET — List reconciliations

Returns reconciliations matching the filters.

Query parameters

string

required

UUID of the store. Must belong to your API key’s account/vendor.

string

YYYY-MM-DD. Returns reconciliations recorded for this specific business day. Mutually exclusive with from/to.

string

Filter to a single operator/cashier.

string

YYYY-MM-DD. Inclusive lower bound for the range filter. Use with to.

string

YYYY-MM-DD. Inclusive upper bound. Use with from.

GET https://app.fire.rest/api/v1/adapters/xmart/cash-management/reconciliations?storeId=550e8400-e29b-41d4-a716-446655440000&businessDayDate=2026-05-06
x-api-key: <your_api_key>

GET response

object[]

Array of reconciliation records — same shape as the POST response data.

{
  "reconciliations": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "accountId": "100",
      "vendorId": "v_blueco_br",
      "storeId": "550e8400-e29b-41d4-a716-446655440000",
      "businessDayDate": "2026-05-06",
      "operatorUid": "op-cashier-123",
      "currency": "BRL",
      "systemCash": 1300.75,
      "declaredCash": 1250.50,
      "discrepancy": -50.25,
      "discrepancyType": "SHORTAGE",
      "authorizationTokenId": null,
      "reportedBy": "apikey:k_ab12cd34",
      "reportedAt": "2026-05-06T16:45:30.000Z",
      "details": {
        "reason": "COUNTING_ERROR",
        "notes": "Short count during evening close",
        "post_close": false,
        "authorization": null
      },
      "createdAt": "2026-05-06T16:45:30.000Z",
      "updatedAt": "2026-05-06T16:45:30.000Z"
    }
  ]
}

Common patterns

End-of-shift flow. Call POST with the operator’s declared count when their shift closes. Display discrepancy and discrepancyType to the supervisor for sign-off.
End-of-day reconcile. Call POST without operatorUid for a store-wide cash count after all shifts have closed.
Audit trail. Use GET with a date range to pull all reconciliations for a store across a period — useful for monthly or quarterly cash audits.

Expected cash

Compute the system-tracked expected cash for a store/day before recording the count.

Authentication

How vendor-scoped API keys and cash-management:* scopes work.

​Authentication

​POST — Record a reconciliation

​Request body

​POST response

​GET — List reconciliations

​Query parameters

​GET response

​Common patterns

​Related

Expected cash

Authentication

Authentication

POST — Record a reconciliation

Request body

POST response

GET — List reconciliations

Query parameters

GET response

Common patterns

Related