View Totals and Reports

This guide explains how to retrieve accumulated transaction totals using the TotalsRepository. This feature is essential for reconciliation, allowing you to view summaries of sales, refunds, and counts for specific operational periods.

You can query totals by Session (periods defined by the host settlement) or by Shift (periods defined locally by your operations).

1. Querying by Session

Sessions are periods typically closed by the closeSession operation. You can retrieve totals for specific dates or ranges.

Repository: TotalsRepository

Get Sessions for a Specific Day

Use getSessions to retrieve all session totals for a given date.

suspend fun getDailyTotals(date: Date) {
    val result = totalsRepository.getSessions(
        date = date,
        wantBrandDetails = true // Include breakdown by card brand (Visa, MC, etc.)
    )
    handleTotalsResult(result)
}

Get a Specific Session

If you know the Session ID (e.g., from a printed receipt), you can query it directly. Note that sessionId is an Int.

suspend fun getSpecificSessionTotal(date: Date, sessionId: Int) {
    val result = totalsRepository.getSession(
        date = date,
        sessionId = sessionId,
        wantBrandDetails = true
    )
    handleTotalsResult(result)
}

Get Sessions Between Dates

To get a report over a date range.

suspend fun getWeeklyTotals(startDate: Date, endDate: Date) {
    val result = totalsRepository.getSessionsBetweenDates(
        initDate = startDate,
        endDate = endDate,
        wantBrandDetails = true
    )
    handleTotalsResult(result)
}

Get Last Session

Retrieves the most recently closed session.

This method returns a GetLastSessionResult wrapper, unlike the others.

suspend fun getLastSessionTotal() {
    val result = totalsRepository.getLastSession()
    // Returns GetLastSessionResult instead of TotalsResult
}

2. Querying by Shift

Shifts are local working periods defined by openShift calls.

Repository: TotalsRepository

Get Shifts for a Specific Day

Retrieve all shifts opened on a specific date.

suspend fun getDailyShiftTotals(date: Date) {
    val result = totalsRepository.getShifts(
        date = date,
        wantBrandDetails = true
    )
    handleTotalsResult(result)
}

Get a Specific Shift

Query a shift by its unique ID. Note that shiftId is a String.

suspend fun getShiftTotal(date: Date, shiftId: String) {
    val result = totalsRepository.getShift(
        date = date,
        shiftId = shiftId,
        wantBrandDetails = true
    )
    handleTotalsResult(result)
}

Get Shifts Between Dates

Retrieve shifts within a specific date range.

suspend fun getWeeklyShiftTotals(startDate: Date, endDate: Date) {
    val result = totalsRepository.getShiftsBetweenDates(
        initDate = startDate,
        endDate = endDate,
        wantBrandDetails = true
    )
    handleTotalsResult(result)
}

Interpreting TotalsResult

Most methods return a RepositoryResult<TotalsResult>. The TotalsResult is a sealed interface with three states:

1. Incoming Data (`TotalsResult.IncomingData`)

Totals were found successfully.

Data: Contains a TotalsModel with the summary (total amount, operation counts, currency, etc.).

2. Empty Data (`TotalsResult.EmptyData`)

No totals were found for the specified criteria (e.g., no sessions on that date).

3. Wrong Identifier (TotalsResult.WrongIdentifierError)

The provided Session ID or Shift ID was incorrect.

Example Handling Logic

fun handleTotalsResult(result: RepositoryResult<TotalsResult>) {
    when (result) {
        is RepositoryResult.Success -> {
            when (val totalsOutcome = result.data) {
                is TotalsResult.IncomingData -> {
                    val data = totalsOutcome.data
                    println("✅ Totals Found for Merchant: ${data.merchantName}")
                    println("Total Sale Amount: ${data.salesTotal}")
                    println("Total Refund Amount: ${data.refundsTotal}")
                }
                is TotalsResult.EmptyData -> {
                    println("⚠️ No data found for this period.")
                }
                is TotalsResult.WrongIdentifierError -> {
                    println("❌ Error: Invalid Session/Shift ID.")
                }
            }
        }
        is RepositoryResult.ConnectionError -> println("❌ Connection Error")
        is RepositoryResult.ProtocolError -> println("❌ Error: ${result.type}")
        else -> {}
    }
}

Next Steps

Issue Digital Receipts: Manage ticket copies.