Generate file-based reports
Learn how to request and read Forage data in file-based reports
This feature is in active development.
Documentation is subject to change. We appreciate your patience and partnership as we continue to build.
Forage file-based reports detail the previous day’s transactions for a merchant or platform.
You can request Payout Summary, Payout Transaction, and Transaction reports. This guide describes each report type, including sample data.
How to request reports
Forage sends the reports as CSVs to your SFTP or S3 server. Contact your Forage representative to share your server details and set up delivery.
Forage reporting endpoints
In addition to requesting file-based reports, you can programmatically create JSON reports via the Forage Payments API reporting endpoints.
Payout Summary reports
A payout is a scheduled funds disbursement from Forage to a merchant or platform. A payout accounts for all transaction types.
A Payout Summary report lists all of the previous day’s payouts. Use this report to review funds disbursements.
| Column name | Type | Description | Example value |
|---|---|---|---|
merchant_payout_id | string | A unique ten character identifier for the merchant payout. In platform reports, this value is blank if the row reflects a payout to a specific merchant on the platform. In reports generated for individual merchants, this value is always populated. | 9f7734298d |
platform_payout_id | string | A unique ten character identifier for the platform payout. This column is not included if the report is generated for an individual merchant. It is only returned in platform reports. If the row reflects a payout to a merchant on the platform, then the value is blank. | 7g8812167b |
merchant_id | string | One of: - A unique identifier for a merchant, provided by Forage. - The constant string many, if a merchant is grouping funds from multiple accounts into a single settlement.This value is blank if the settlement reflects a platform instead of a merchant payout. | 82f3c65080 |
fns_id | string | A merchant’s unique FNS number. This value is blank if the settlement reflects a platform instead of a merchant payout. | 1811145 |
payout_issued_date | string | A date-stamp of when the payout was created. | 06/18/2024 |
expected_deposit_date | string | A date-stamp of when Forage expects the payout to be deposited. This is typically the payout_issued_date plus one business day, as the ACH method is next-day. | 06/19/2024 |
total_purchases | number | The total amount in USD of all of the purchases included in this payout. | 180.98 |
total_refunds | number | The total amount in USD of all of the refunds included in this payout. | 0.00 |
total_chargebacks | number | The total amount in USD of refunds paid to customers as the result of dispute resolutions during this payout period. The total_chargebacks value is distinct and not included in the total_refunds value. | 0.00 |
total_positive_adjustments | number | If any, the total arbitrary amount in USD that has been added to the settlement. For example, this could happen in the rare case that Forage corrects a previous settlement. | 0.00 |
total_negative_adjustments | number | If any, the total arbitrary amount in USD that has been deducted from the settlement. For example, this could happen in the rare case that Forage corrects a previous settlement. | 0.00 |
merchant_net_settlement | number | The net amount sent to the merchant, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. This value is blank if the settlement reflects a platform instead of a merchant payout. | 27.03 |
platform_net_settlement | number | The net amount sent to the platform, if applicable, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. This column is not included if a platform was not involved in the transaction. | |
merchant_destination_account_ref | string | A unique reference hash for the merchant bank account that received funds settlement for this payment. This value is blank if the payout reflects a platform instead of a merchant settlement. | 20b00b123 |
Payout Transaction reports
A Payout Transaction report lists all transactions included in a particular payout. Use this report to analyze every transaction associated with a single payout.
| Column name | Type | Description | Example value |
|---|---|---|---|
merchant_id | string | A ten character identifier for a merchant, provided by Forage. | a0040a0020 |
fns_id | string | A merchant’s unique FNS number. | 1234567 |
payout_issued_date | string | A date-stamp of when the payout was created. | 06/18/2024 |
expected_deposit_date | string | A date-stamp of when Forage expects the payout to be deposited. This is typically the payout_issued_date plus one business day, as the ACH method is next-day. | 06/19/2024 |
recorded_date | string | The date and time of the transaction, formatted as an ISO 8601 string in the UTC timezone. | 2024-11-04T14:00:00Z |
payment_method | string | The funding type of the transaction. One of: - SNAP- EBT_Cash | SNAP |
transaction_type | string | The type of transaction. One of: - Purchase- Void_Purchase- Purchase_With_Cash_Back- Void_Purchase_With_Cash_Back- Refund- Void_Refund- Withdrawal- Void_Withdrawal- Chargeback | Refund |
transaction_amount | number | The total amount in USD charged, voided, or refunded to the customer. | 28.15 |
merchant_net_settlement | number | The net amount sent to the merchant, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. | 27.03 |
platform_net_settlement | number | If the transaction was processed via a platform that hosts multiple merchants, then this is the net amount sent to the host platform, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. This column is not included if a platform was not involved in the transaction. | 1.23 |
merchant_payout_id | string | A unique ten character identifier for the transaction's merchant payout. | 9f7734298d |
platform_payout_id | string | A unique ten character identifier for the transaction's platform payout. This column is not included if the report is generated for an individual merchant. It is only returned in platform reports. The platform_payout_id value is blank if the transaction does not have an associated platform payout. | 7g8812167b |
order_id | string | For Fully Hosted and Custom integrations, a unique identifier for the order associated with the transaction. This value is not returned for SDK integrations. | b7b04a4b5c |
external_order_id | string | A unique identifier for the order as created by the merchant or platform (not Forage). This typically corresponds to an identifier in the merchant or platform’s database, so it can be used as a reference to look up the transaction. | 1f2ee410-5b47-4130-aec2-40f5eb2108f5 |
payment_id | string | A unique identifier for the payment transaction. | 4be98347f6 |
refund_id | string | If the transaction_type is Refund, a unique identifier for the refund transaction.This value is blank for all other transaction types. | cbe72b8320 |
chargeback_id | string | If the transaction_type is Chargeback, a unique identifier for the chargeback transaction.This value is blank for all other transaction types. | d200020430 |
merchant_destination_account_ref | string | A unique reference hash for the bank account that received the funds settlement for this payment. | 20b0b0123 |
external_location_id | string | A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order. For example, this field could specify which location of a grocery store chain fulfilled an order. | 6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9 |
description | string | A description of the transaction, as provided by the merchant or platform when the transaction was created. | An EBT SNAP payment |
Transaction reports
A Transaction report lists all financial operations from the previous day that involved a flow of funds, whether or not they were included in a payout.
Use a Transaction report to reconcile your accounting books against the Forage ledger.
| Column name | Type | Description | Example value |
|---|---|---|---|
merchant_id | string | A ten character identifier for a merchant, provided by Forage. | a0i404a0020 |
fns_id | string | A merchant’s unique FNS number. | 1234567 |
recorded_date | string | The date and time of the transaction, formatted as an ISO 8601 string in the UTC timezone. | 2024-11-04T14:00:00Z |
payment_method | string | The funding type of the transaction. One of: - SNAP- EBT_Cash | SNAP |
transaction_type | string | The type of transaction. One of: - Purchase- Void_Purchase- Purchase_With_Cash_Back- Void_Purchase_With_Cash_Back- Refund- Void_Refund- Withdrawal- Void_Withdrawal- Chargeback | Refund |
transaction_amount | number | The total amount in USD charged, voided, or refunded to the customer. | 28.15 |
merchant_net_settlement | number | The net amount sent to the merchant, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. | 27.03 |
platform_net_settlement | number | If the transaction was processed via a platform that hosts multiple merchants, then this is the net amount sent to the host platform, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions. This column is not included if a platform was not involved in the transaction. | 0.00 |
order_id | string | For Fully Hosted and Custom integrations, a unique identifier for the order associated with the transaction. This value is not returned for SDK integrations. | b7b04a4b5c |
external_order_id | string | A unique identifier for the order as created by the merchant or platform (not Forage). This typically corresponds to an identifier in the merchant or platform’s database, so it can be used as a reference to look up the transaction. | 1f2ee410-5b47-4130-aec2-40f5eb2108f5 |
payment_id | string | A unique identifier for the payment transaction. | 4be98347f6 |
refund_id | string | If the transaction_type is Refund, a unique identifier for the refund transaction.This value is blank for all other transaction types. | cbe72b8320 |
chargeback_id | string | If the transaction_type is Chargeback, a unique identifier for the chargeback transaction.This value is blank for all other transaction types. | d200020430 |
merchant_destination_account_ref | string | A unique reference hash for the bank account that received funds settlement for this payment. | 20b0b0123 |
external_location_id | string | A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order. For example, this field could specify which location of a grocery store chain fulfilled an order. | 6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9 |
description | string | A description of the transaction, as provided by the merchant or platform when the transaction was created. | An EBT SNAP payment |
Updated 11 days ago