Understanding Forage Reporting

What Forage reporting offers

Forage provides automated reports in CSV format that help merchants and platforms track transactions and payouts. Reports are generated daily at approximately 10:00 PM UTC and transferred via SFTP.

Three report types

Forage provides three report types. The report name depends on how the report is delivered (API or SFTP), but the underlying data and purpose are the same. When you schedule reports in the Forage Dashboard, those reports are delivered via SFTP, so the report names shown in the Dashboard match the SFTP-delivered report names.

For SFTP delivery, you'll receive one of three report flavors depending on your business setup:

Three delivery channels

Forage exposes the same underlying report data through three delivery channels. Pick the one that matches how much setup and automation your team wants.

Forage Dashboard

The Dashboard suits small businesses or merchants who want a simple, manual way to pull transaction data. It needs no technical setup and works well for occasional reporting.

Dashboard reports give you a single CSV file with your choice of fields, requested manually each time. The Dashboard is also where you configure scheduled reports, which Forage then delivers automatically via SFTP. For more automation and a wider set of data points, use API or SFTP reports instead.

API reports (JSON)

The Forage API is the right fit when you want more automation but still control when and how reports are retrieved. The structured JSON format integrates cleanly with business systems. The Reporting API and the SFTP CSV reports return the same underlying fields, so the data set is identical regardless of delivery channel.

API reports require development resources to set up and maintain, but you can automate the requests on your own schedule. For fully automated delivery without code, use SFTP reports.

To call the Reporting API you need a bearer token with the reporting scope; see Authenticate with Forage and Register an app. Three GET endpoints cover the three report types described above:

• Retrieve a Transaction Report returns the Transaction Log.
• Retrieve a Payout Report returns the Payout Summary.
• Retrieve a Payout Transaction Report returns the Payout Transactions.

Fully Hosted and Custom Checkout integrations also have a fourth endpoint, Retrieve an Order Report, which isn't part of the three report types above.

Each reference page includes a full example request and response. The Transaction Report and Payout Report take required start_date and end_date query parameters; the Payout Transaction Report is scoped by a payout_id path parameter instead, with no date range needed. All three support optional limit (default 100, max 1000) and cursor for paging through results. Requests are scoped to one merchant with the Merchant-Account header; omit it on a platform account (an account that manages more than one merchant, covered below in Two fee models) to get results across every merchant.

In practice, requests return results immediately, with no pending or "report not ready" state to poll for. A missing or expired token returns a 401. A missing or invalid start_date/end_date (or a malformed payout_id) returns a 400; a payout_id that doesn't match an existing payout returns a 404. Forage also rate-limits the Reporting API (a 429 response) to protect the service under heavy load.

SFTP reports (CSV)

SFTP reports are fully automated and configured through the Forage Dashboard. They work best for large businesses and enterprises that need scheduled, hands-off reporting at high volume.

SFTP delivery requires minimal technical setup to verify file transfers and grant initial server access. For an occasional, simpler alternative, download reports through the Forage Dashboard.

Two fee models: merchant or platform

Forage applies one of two fee models to every merchant. The fee model determines which CSV report you receive and which fields appear in it.

The fee model determines which of the two merchant CSV reports you receive. The Platform CSV report is a separate report aimed at the platform itself, not at any individual merchant.

If you don't know which model applies to your account, your Forage contact can confirm.

How payouts and settlement relate to reports

Settlement is when Forage actually moves money to your bank account. It runs on a fixed daily schedule called the payout cycle. Reports are tied to the payout cycle, not to real-time transaction events. Two facts about settlement timing shape how the data shows up.

Settlement delays vary by merchant. For example, T+3 means a Monday transaction settles on Thursday. The recorded_date on a transaction is when the transaction occurred; the payout_issued_date and expected_deposit_date are when funds move. A reconciliation comparing dates across systems has to account for this gap.

Reports are generated once per day at approximately 10:00 PM UTC. A transaction that lands after that cutoff appears in the next day's report, not the current day's. If a report needs to be regenerated (for example, after a correction), the original report's timestamp is retained but the attempt number in the filename increments.

The Payout Transaction report and Payout Summary together describe the payout itself: the sum of money Forage moved to the merchant's destination account on a given day. The optional Transaction Log is broader: it captures every fund movement from the previous day, including transactions that aren't part of any payout (such as standalone fees or adjustments). Use the Transaction Log when you need a complete audit trail; use the Payout reports when you're reconciling against actual deposits.

How the numbers tie out

Use this chain when a deposit doesn't match what you expected:

1. Each row in the Payout Transaction Report is a single money movement: a purchase, a refund, a fee, or an adjustment.
2. The Payout Summary rolls those rows up for the payout into the total_* fields and forage_fee.
3. merchant_net_settlement is the net of those totals. It is the amount Forage actually moves for that payout. Treat it as the authoritative figure. If your own recomputation from the other totals doesn't match exactly, check for rounding or timing effects before assuming there's an error on Forage's side.
4. That amount lands in your bank account on expected_deposit_date, which is T+N after the transactions occurred. A given deposit reflects an earlier day's transactions, not that day's sales.

So a deposit that doesn't match a day's sales is expected: it is net of refunds, chargebacks, fees, and adjustments, and it is shifted later by the settlement delay.

Two details to know when reading the totals: total_chargebacks is tracked separately from total_refunds, and every one of these total fields (total_refunds, total_chargebacks, total_void_purchases, total_void_refunds) is reported as a positive amount, even the ones that reduce what's owed.

Putting it together

Three choices determine the CSV report you receive and the fields it contains: the report type (Transaction, Payout Summary, or Payout Transaction), the delivery channel (Dashboard, API, or SFTP), and the fee model on your account (Charging to Merchant or Charging to Platform). All reports run on the same daily cycle (approximately 10:00 PM UTC) and the same settlement timing rules, so reconciliation logic written for one channel translates cleanly to another.

Related topics

• How-to: How to set up SFTP reports.
• Reference: CSV report conventions, Merchant (Charging to Merchant) CSV report, Merchant (Charging to Platform) CSV report, Platform CSV report, Transaction type and payment method values.