Statements

Luqra generates a monthly statement for each originator: a PDF report and a CSV export itemizing every transaction in the period. Use the Statements API to list available statements and download either format.

List statements

curl "https://{api-host}/v1/statements" \
  -H "Authorization: Bearer $YOUR_API_KEY"

Query parameters

ParameterTypeDefaultDescription
cursorstring--Opaque pagination token. Omit on the first request; pass the nextCursor from the previous response to fetch the next page.
limitinteger20Results per page (1--100)
originatorIdUUID--Filter to a single originator
periodYearinteger--Filter by year (2000--2999)
periodMonthinteger--Filter by month (1--12)

Response

All total*MinorUnits fields are numbers in minor units (cents for USD). For example, 5000000 = $50,000.00.

{
  "data": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "originatorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "periodYear": 2026,
      "periodMonth": 3,
      "timezone": "America/New_York",
      "generatedAt": "2026-04-01T02:00:00.000Z",
      "pdfReady": true,
      "csvReady": true,
      "pdfSizeBytes": 102400,
      "csvSizeBytes": 8192,
      "totalPaymentCount": 150,
      "totalReturnCount": 3,
      "totalProcessingVolumeMinorUnits": 5000000,
      "totalReturnVolumeMinorUnits": 75000,
      "totalDiscountFeesMinorUnits": 5000,
      "totalTransactionFeesMinorUnits": 3750,
      "totalReturnFeesMinorUnits": 7500,
      "totalServiceFeesMinorUnits": 3000
    }
  ],
  "meta": {
    "timestamp": "2026-05-01T10:00:00.000Z",
    "pagination": {
      "limit": 20,
      "nextCursor": null
    }
  }
}

Fields

FieldTypeDescription
idUUIDStatement ID
originatorIdUUIDOriginator this statement belongs to
periodYearintegerBilling year
periodMonthintegerBilling month (1--12)
timezonestringIANA timezone used for period boundaries
generatedAtISO 8601When the statement was generated. Generation is anchored to the 1st of the month following the period end in the originator's configured timezone, then shifted forward by the originator's configured delay. As a result, generatedAt can vary across originators even for the same period
pdfReadybooleanWhether the PDF is available for download
csvReadybooleanWhether the CSV export is available for download
pdfSizeBytesinteger | nullPDF file size in bytes. null until the PDF is rendered.
csvSizeBytesinteger | nullCSV file size in bytes. null until the CSV is generated.
totalPaymentCountintegerPayments in the period, including payments that were returned before completing
totalReturnCountintegerReturns in the period
totalProcessingVolumeMinorUnitsnumberTotal payment volume, including payments that were returned before completing
totalReturnVolumeMinorUnitsnumberTotal returned payment volume
totalDiscountFeesMinorUnitsnumberVolume-based discount fees charged in the period
totalTransactionFeesMinorUnitsnumberPer-transaction flat fees
totalReturnFeesMinorUnitsnumberReturn fees charged
totalServiceFeesMinorUnitsnumberMonthly service fees charged

Error responses

CodeReason
400Invalid query parameters
401API key is missing, malformed, unknown, revoked, or expired
403The API key is valid but is not an organization key

5xx responses aren't listed here. See Errors for the full status and error-code reference.

Get a statement download URL

Returns a short-lived signed URL for downloading the statement PDF or its CSV export. The URL expires in 15 minutes.

curl "https://{api-host}/v1/statements/STATEMENT_ID/download" \
  -H "Authorization: Bearer $YOUR_API_KEY"

To download the CSV export instead:

curl "https://{api-host}/v1/statements/STATEMENT_ID/download?format=csv" \
  -H "Authorization: Bearer $YOUR_API_KEY"

Query parameters

ParameterTypeDefaultDescription
formatstringpdfWhich rendition to download: pdf or csv

The CSV export contains every line item in the statement period -- one row per transaction with the columns Date, Type, Contact, Description, External ID, Amount, Discount Fee, Transaction Fee, and Return Fee. Type is one of PAYMENT, RETURN, FEE_COLLECTION, or REFUND, and amounts are decimal dollar values. Outbound payments carry a negative Amount; all other rows are positive. Refund rows only appear for refunds paid back to the originator. Unlike the PDF, which summarizes activity by day, the CSV is the complete transaction ledger.

Response

{
  "data": {
    "url": "https://storage.googleapis.com/luqra-statements/...",
    "expiresAt": "2026-05-01T10:15:00.000Z"
  },
  "meta": { "timestamp": "2026-05-01T10:00:00.000Z" }
}

The url is a pre-signed download URL that streams the file directly with an attachment content disposition (application/pdf or text/csv). Use it before expiresAt; request a fresh URL whenever you need to download again.

Error responses

CodeReason
400Invalid statement ID format, or format is not pdf or csv
401API key is missing, malformed, unknown, revoked, or expired
403The API key is valid but is not an organization key
404Statement not found or does not belong to your organization
409Requested file is not yet generated -- check pdfReady: true (or csvReady: true for format=csv) before requesting a download URL

5xx responses aren't listed here. See Errors for the full status and error-code reference.