FlintflintDocs

Reports

Reports turn order, payment, Flint billing, balance, payout, and tax history into versioned CSV files. Generation is asynchronous: create a report, wait for report.succeeded or poll the resource, then download the file with your API key. Report routes are API-key-only, and reports are scoped to the environment the key belongs to.

A report covers one currency over one closed interval. interval_start_at is inclusive, interval_end_at is exclusive, and an end in the future is rejected. payments_itemized_v1 and tax_summarized_v1 intervals are limited to 366 days; other itemized intervals are limited to 90 days. timezone changes how timestamp columns are rendered. Payout arrival is a calendar date rather than an instant, so payout reports also interpret the interval boundaries as local calendar dates in this timezone. Each report type matches the interval on its own timestamp or date (order close, capture time, Flint billing entry occurrence, balance transaction time, payout arrival), so two report types over the same dates are not expected to select the same underlying activity.

A report is pending, succeeded with an expiring download, or failed with a failure_reason. Flint uses data_unavailable when payout allocations or tax lineage have not landed yet, and limit_exceeded when generation crosses a documented bound. Download requests redirect to a short-lived private file URL. Downloads expire 24 hours after success and then return 410; create the report again with a new Idempotency-Key to get a fresh file.

Use merchant_billing_itemized_v1 for the line-by-line history behind what you owe Flint and the account credit you hold, covering event fees, Flint subscription invoice charges, finalized fee corrections, credit issued and applied, collections, collection reversals, and write-offs. See Flint Billing. For the transactions in one specific payout, GET /v1/payouts/{payout_id}/entries on money movement answers directly without generating a report. See Reports for column layouts and reconciliation recipes.

Endpoints

Download a report#

GET/v1/report-downloads/{report_download_id}Requires scope: reports.read or reports.write

Authorizes the stable Flint download URL and redirects to a short-lived private file URL.

Path parameters
report_download_idstringrequired

Flint report download ID.

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPERATE_LIMIT_EXCEEDEDREPORTING_UNAVAILABLEREPORT_DOWNLOAD_EXPIREDREPORT_NOT_FOUNDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/report-downloads/{report_download_id} \
  -H "Authorization: Bearer YOUR_API_KEY"

List reports#

GET/v1/reportsRequires scope: reports.read or reports.write

Lists reports in descending creation order using opaque pagination.

Query parameters
page_sizeinteger

Number of reports to return.

page_tokenstring

Opaque token returned by the previous page.

Response · 200
dataarray of one ofrequired
metaobject
next_page_tokenstring
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_PAGE_SIZEINVALID_PAGE_TOKENINVALID_REQUESTRATE_LIMIT_EXCEEDEDREPORTING_UNAVAILABLESERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/reports \
  -H "Authorization: Bearer YOUR_API_KEY"

Create a report#

POST/v1/reportsIdempotentRequires scope: reports.write

Creates an idempotent asynchronous CSV report. Poll the returned report until it succeeds or fails.

Request body
currencystringrequired

Three-letter ISO 4217 currency. Reports never combine currencies.

interval_end_atstringrequired

Exclusive report interval end instant.

interval_start_atstringrequired

Inclusive report interval start instant.

report_typeenumrequired
orders_itemized_v1payments_itemized_v1balance_transactions_itemized_v1payouts_itemized_v1tax_itemized_v1tax_summarized_v1merchant_billing_itemized_v1
timezonestring

IANA timezone used for date bucketing. Defaults to UTC.

Response · 201
dataone ofrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDIDEMPOTENCY_KEY_REUSEDIDEMPOTENCY_KEY_TOO_LONGINSUFFICIENT_SCOPEINVALID_CURRENCYINVALID_IDEMPOTENCY_KEYINVALID_INTERVAL_END_ATINVALID_INTERVAL_START_ATINVALID_REPORT_INTERVALINVALID_REPORT_TYPEINVALID_REQUESTINVALID_REQUEST_BODYINVALID_TIMEZONERATE_LIMIT_EXCEEDEDREPORTING_UNAVAILABLEREPORT_INTERVAL_INCOMPLETEREPORT_INTERVAL_TOO_LARGESERVICE_UNAVAILABLETOO_MANY_PENDING_REPORTS
Bash
curl -X POST https://api.withflintpay.com/v1/reports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a-unique-key" \
  -d '{
    "currency": "USD",
    "interval_end_at": "",
    "interval_start_at": "",
    "report_type": "orders_itemized_v1"
  }'

Get a report#

GET/v1/reports/{report_id}Requires scope: reports.read or reports.write

Returns one report and its terminal download or failure details when available.

Path parameters
report_idstringrequired

Flint report ID.

Response · 200
dataone ofrequired
metaobject
request_idstring

Error codes

AUTH_REQUIREDINSUFFICIENT_SCOPEINVALID_REQUESTRATE_LIMIT_EXCEEDEDREPORTING_UNAVAILABLEREPORT_NOT_FOUNDRESOURCE_NOT_FOUNDSERVICE_UNAVAILABLE
Bash
curl https://api.withflintpay.com/v1/reports/{report_id} \
  -H "Authorization: Bearer YOUR_API_KEY"
Rate this doc