Reporting CSV Conventions

This reference covers the conventions that apply to every Forage CSV report: file naming, delivery schedule, formatting rules, ID uniqueness, settlement timing, and the field definitions shared across all report flavors. Each individual CSV report reference page points back here for everything in this list. For step-by-step instructions to set up SFTP delivery, see How to set up SFTP reports.

About this reference

The three Forage CSV reports (Merchant (Charging to Merchant), Merchant (Charging to Platform), and Platform) share most of their structure. The conventions below apply to all three. The per-report reference pages cover only what's specific to that report flavor.

Delivery schedule

Reports are generated daily at approximately 10:00 PM UTC.
The report is first saved as a temporary file during upload: filename.tmp.
Once the upload is complete, the file is renamed to filename.csv so recipients only access fully written reports.
Reports are uploaded to the folders you choose on your SFTP server.

Formatting rules

All reports use the same column names, so a field that appears in more than one report carries the same meaning everywhere. Some fields are left blank instead of showing a zero value (for example, an empty cell rather than 0.00). You can choose which fields you receive, but the formatting itself stays the same across reports.

ID uniqueness conventions

All 10-character IDs provided by Forage are unique within their respective fields.

For example, every order_id is unique within the list of order IDs. These IDs are not globally unique across different fields; the same 10-character sequence might also appear as a merchant_id, payment_id, or in another field.

Settlement delay

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. Account for this gap when reconciling Forage data against bank deposits.

Shared field definitions

Every Forage CSV report (Payout Transaction, Payout Summary, and Transaction Log, across all three report flavors) pulls from the same shared set of column definitions. This table is the single source of truth for shared field semantics. Per-report reference pages list which of these fields appear in each table and add any report-specific fields on top.

The transaction_type and payment_method value enumerations are documented in Transaction type and payment method values.

Field	Description	Sample
`merchant_id`	A 10-character unique hash identifying the merchant associated with this transaction.	`gxe37pc24y`
`fns_id`	The FNS (Food and Nutrition Service) number of the merchant that received the payout including this transaction.	`9900099`
`recorded_date`	The date and time of the transaction, formatted as an ISO 8601 string in the UTC timezone.	`2023-12-28T00:08:38.890Z`
`payout_issued_date`	The date the payout was created, formatted as `M/D/YYYY` (US, no leading zeros). Only populated for Payout Transaction Reports.	`1/3/2024`
`expected_deposit_date`	The date Forage expects the payout to be deposited, formatted as `M/D/YYYY` (US, no leading zeros). Typically the `payout_issued_date` plus one business day, if the ACH (the bank-transfer network used to move funds) method is next-day.	`1/4/2024`
`payment_method`	The payment method (tender) used for the transaction. See Payment methods for the full enum.	`SNAP`
`transaction_type`	The type of the transaction. See Transaction types for the full enum.	`Purchase`
`transaction_amount`	The total amount in USD charged, voided, or refunded to the customer.	`126.05`
`forage_fee`	The amount of Forage fees applied to the transaction.	`3.96`
`merchant_net_settlement`	The net amount sent to the merchant, equal to the sum of purchases minus refunds, chargebacks, fees, and adjustments. Blank if the settlement reflects a platform instead of a merchant payout.	`122.09`
`platform_net_settlement`	The net amount sent to the platform, if applicable. Blank if the settlement reflects a merchant payout and no platform was involved.	`0.00`
`order_id`	A 10-character unique hash identifying the order for Fully Hosted Checkout. Blank for Custom Checkout, SDK, and POS integrations, which identify orders via `external_order_id` instead.	`a9a7226jm8`
`external_order_id`	A unique, merchant or platform-provided identifier for the order that corresponds to their own database, supplied when the payment, session, or order is created.	(Platform-defined ID)
`payment_id`	A 10-character unique hash identifying the related `Payment` or `OrderPayment`. Blank for fee rows (`Balance_Inquiry_Fee`, `Refund_Processing_Fee`) and adjustments.	`mn0yo1orjw`
`refund_id`	A 10-character unique hash identifying the related `Refund` or `OrderRefund`.	`56us47lbpo`
`chargeback_id`	A 10-character unique hash identifying the chargeback transaction. Present only when `transaction_type` is `Chargeback`.	`luw8sozitr`
`merchant_payout_id`	A 10-character unique hash identifying the merchant payout. Present only in Payout Transaction Reports.	`jakqbi64tv`
`platform_payout_id`	A 10-character unique hash identifying the platform payout. Present only if the transaction is part of a platform payout, and only in Payout Transaction Reports.	`atn1ulwziv`
`merchant_destination_account_ref`	A 10-character unique hash for the merchant's destination bank account. Blank if settled to a platform account.	`c45b20e98a`
`external_location_id`	A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order.	(Platform-defined)
`description`	A text field supplied by the merchant or platform (not Forage) that can be used for descriptive purposes.	(User-defined)
`corporation_ref`	A 10-character unique hash referencing the corporation linked to the onboarding merchant. A corporation is the umbrella legal entity the merchant is nested under. If none provided, Forage creates one.	`tp43855aag`
`merchant_group_ref`	A 10-character unique hash referencing the merchant group associated with the merchant. A merchant group is a collection of merchant IDs. If none provided, Forage creates one.	`o73bnhm6pn`

📘
API version requirement
The external_order_id field requires Forage Version 2023-05-15 or later. Pass 2023-05-15 as the API-Version header on a per-request basis, or set the version for all requests in the Forage Dashboard. Only one external_order_id can be passed as a query param at a time.

Transaction Log (on request)

Every CSV report has an optional third file (a Transaction Log) that's available on request. It captures every fund movement from the previous day, including transactions that aren't part of a payout, so you can reconcile your accounting records against the Forage ledger and confirm that every transaction is accounted for.

The Transaction Log covers merchant and FNS IDs, recorded dates, payment methods, transaction amounts, unique identifiers for orders, payments, refunds, and chargebacks, plus additional metadata. The per-report reference pages list the exact fields included in each flavor.

To enable a Transaction Log on your SFTP report, see How to set up SFTP reports — Enable a Transaction Log.

Filename pattern

Each report uses a filename that encodes its type, timing, and version.

For merchant reports:

Payout Summary: %Y%m%d%H%M_AAA_BBB_Merchant_Platform_Forage_Payout.csv
Payout Transaction Report: %Y%m%d%H%M_AAA_BBB_Merchant_Platform_Forage_PayoutTransaction.csv

For platform reports:

Payout Summary: %Y%m%d%H%M_AAA_BBB_Platform_Forage_Payout.csv
Payout Transaction Report: %Y%m%d%H%M_AAA_BBB_Platform_Forage_PayoutTransaction.csv

Filename components

Component	Description
`%Y%m%d%H%M`	The UTC timestamp when the report was generated, written as year, month, day, hour, minute (for example, `202606182200`). On a revision, the original timestamp is retained. `HHMM` can be `0000` or randomized.
`AAA`	The attempt number for file generation. Starts at `001` and increments for each correction.
`BBB`	The file format's version number. Starts at `01` and increments for each new specification.
`Merchant`	The recipient type (`merchant`, `merchant group`, or `corporation`). The merchant name is sanitized (special characters removed, camel-cased). Not present in platform reports.
`Platform`	The name of the e-commerce platform the merchant operates on. If a merchant sells through a third-party platform, the name of that platform appears here. If the merchant uses its own system, the platform is the same as the merchant's name.

When more than one file shares the same %Y%m%d%H%M timestamp, the file with the highest AAA attempt number is the most recent correction and supersedes the earlier ones. Use the highest attempt number as the authoritative version for that report.