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

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,
      "totalFeeCount": 150,
      "totalProcessingVolumeMinorUnits": 5000000,
      "totalReturnVolumeMinorUnits": 75000,
      "totalDiscountFeesMinorUnits": 5000,
      "totalDiscountRateMinorUnits": 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 processed in the period
`totalReturnCount`	integer	Returns in the period
`totalFeeCount`	integer	Fee transactions in the period
`totalProcessingVolumeMinorUnits`	number	Total payment volume processed
`totalReturnVolumeMinorUnits`	number	Total returned payment volume
`totalDiscountFeesMinorUnits`	number	Volume-based discount fees charged in the period
`totalDiscountRateMinorUnits`	number	Deprecated. Mirrors `totalDiscountFeesMinorUnits`. The name is a misnomer -- the value is an amount, not a rate. Migrate to `totalDiscountFeesMinorUnits`; this field will be removed in a future release.
`totalTransactionFeesMinorUnits`	number	Per-transaction flat fees
`totalReturnFeesMinorUnits`	number	Return fees charged
`totalServiceFeesMinorUnits`	number	Monthly service fees charged

Error responses

Code	Reason
`400`	Invalid query parameters
`401`	Missing or invalid API key

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 contains every line item in the statement period -- one row per transaction with the columns Date, Type, Counterparty, 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. Unlike the PDF, whose itemized section lists only returns, refunds, and fee collections, 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

Code	Reason
`400`	Invalid statement ID format, or `format` is not `pdf` or `csv`
`401`	Missing or invalid API 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

Managing Contacts

Testing in Sandbox