Statements
Luqra generates a monthly statement for each originator: a PDF report and a CSV export itemizing the originator's payments for 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
| Parameter | Type | Default | Description |
|---|---|---|---|
cursor | string | -- | Opaque pagination token. Omit on the first request; pass the nextCursor from the previous response to fetch the next page. |
limit | integer | 20 | Results per page (1--100) |
originatorId | UUID | -- | Filter to a single originator |
periodYear | integer | -- | Filter by year (2000--2999) |
periodMonth | integer | -- | 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
| Field | Type | Description |
|---|---|---|
id | UUID | Statement ID |
originatorId | UUID | Originator this statement belongs to |
periodYear | integer | Billing year |
periodMonth | integer | Billing month (1--12) |
timezone | string | IANA timezone used for period boundaries |
generatedAt | ISO 8601 | When 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 |
pdfReady | boolean | Whether the PDF is available for download |
csvReady | boolean | Whether the CSV export is available for download |
pdfSizeBytes | integer | null | PDF file size in bytes. null until the PDF is rendered. |
csvSizeBytes | integer | null | CSV file size in bytes. null until the CSV is generated. |
totalPaymentCount | integer | Payments whose debit to settlement reached the bank within the period, whether or not they have since been returned |
totalReturnCount | integer | Payments returned within the period, whether or not they reached the bank within it |
totalProcessingVolumeMinorUnits | number | Volume of the payments counted by totalPaymentCount |
totalReturnVolumeMinorUnits | number | Volume of the payments counted by totalReturnCount |
totalDiscountFeesMinorUnits | number | Volume-based discount fees. Sums the CSV's Discount Fee column |
totalTransactionFeesMinorUnits | number | Per-transaction flat fees. Sums the CSV's Transaction Fee column |
totalReturnFeesMinorUnits | number | Return fees. Sums the CSV's Return Fee column |
totalServiceFeesMinorUnits | number | Monthly account service fees. Has no CSV column, since it is charged per period rather than per payment |
Error responses
| Code | Reason |
|---|---|
400 | Invalid query parameters |
401 | API key is missing, malformed, unknown, revoked, or expired |
403 | The 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
| Parameter | Type | Default | Description |
|---|---|---|---|
format | string | pdf | Which rendition to download: pdf or csv |
The CSV export itemizes the originator's payments for the period, one row per payment, with the columns Date, Status, Type, Contact, Description, External ID, Amount, Discount Fee, Transaction Fee, Return Fee, Completed At, and Returned At. Amounts are decimal dollar values and always positive; Type carries Debit for an inbound payment and Credit for an outbound one. Status is the payment's status at the moment the statement was generated, the same value the Payments API reports (see Payment lifecycle). Rows are ordered oldest first.
A payment appears when its debit to settlement reached the bank within the period, or when it was returned within the period. Date is the day the debit reached the bank, which is also the sort key. Completed At and Returned At are empty until the payment completes or is returned. Every date and time is in the statement's timezone.
A payment that reached the bank in one period and was returned in a later one appears in both exports: its discount and transaction fees on the first, its return fee on the second, and zero in the other columns each time, so a fee is never counted twice. Refunds and fee debits produce no rows. Unlike the PDF, which summarizes activity by day, the CSV is the itemized ledger behind those totals.
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
| Code | Reason |
|---|---|
400 | Invalid statement ID format, or format is not pdf or csv |
401 | API key is missing, malformed, unknown, revoked, or expired |
403 | The API key is valid but is not an organization key |
404 | Statement not found or does not belong to your organization |
409 | Requested 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.