With the /reporting/ endpoints, you can:

Retrieve an Order report: GET /reporting/orders/
Retrieve a Payout Report: GET /reporting/payouts/
Retrieve a Payout Transaction Report: GET /reporting/payouts/{payout_id}/transactions/
Retrieve a Transaction Log: GET /reporting/transactions/

The API responds to every /reporting/ request with a list of paginated results.

Query params

The following query params tell Forage what results to collect for a report:

`start_date` | date

The date that the reporting period starts, represented as an ISO 8601 date string, inclusive. The result set includes all reported items that occurred on the date.

The Forage server uses Pacific time, so, for example, a transaction that occurred at 2 AM EST on 2021-01-31 is included in the results for 2021-01-30.

`end_date` | date

The date that the reporting period ends, represented as an ISO 8601 date string, inclusive. The result set includes all reported items that occurred on the date.

The Forage server uses Pacific time, so, for example, a transaction that occurred at 2 AM on 2021-01-31 is included in the results for 2021-01-30.

`limit` | integer

The maximum number of objects to include in the results array. Not to exceed 1000. If the limit exceeds 1000, then Forage returns a 400 error response.

Defaults to 100.

`cursor` | string

The starting point for the results, as returned in a previous /reporting/ request. Find a cursor in the URL returned in the next and/or previous response values.

📘
Check Endpoint Query Parameters
Not all endpoints support the same query parameters. Refer to each endpoint's reference page for details like accepted start_date and end_date.

`Report` object

Example Order `Report`

{
  "next": "https://api.sandbox.joinforage.app/reporting/orders/?cursor=cD0yMDIzLTAxLTMxKzIxJTNBMzElM0ExNC40NTUxNjMlMkIwMCUzQTAw&end_date=2021-02-28&start_date=2021-01-31",
  "previous": null,
  "results": [
    {
      "ref": "b085e45a54",
      "status": "draft",
      "snap_eligible_total": 25.99,
      "ebt_cash_eligible_total": 21.23,
      "remaining_total": 44.39,
      "sales_tax_applied": 5.12,
      "snap_paid": 86.29,
      "ebt_cash_paid": 15.22,
      "credit_debit_paid": 67.9,
      "merchant_fns_number": "1234567",
      "created": "2021-06-15T00:11:50.000000Z-07:00",
      "success_date": "2021-06-16T00:11:50.000000Z-07:00",
      "payments": [
        "cd62e45f33",
        "a2f4e45665"
      ],
      "refunds": [
        "aaabe45432",
        "7e84e45db7"
      ],
      "psp_customer_id": "string",
      "external_order_id": "1f2ee410-5b47-4130-aec2-40f5eb2108f5"
    }
  ]
}

No matter the type of report, on success all /reporting/ endpoints respond with the following fields:

Property	Type	Description
`next`	string	A URL that you can send a `GET` to in order to retrieve the next set of results. Alternatively, you can retrieve the `cursor` value from the URL and pass it in the body of a new request. This value is `null` if there are no more results.
`previous`	string	A URL that you can send a `GET` to in order to retrieve the previous set of results. Alternatively, you can retrieve the `cursor` value from the URL and pass it in the body of a new request. The value is `null` if the response includes the first set of results.
`results`	array	An array of objects that varies depending on the type of report requested. Refer to Report types for report-level details.

Report types

Order Reports

/reporting/orders/

📘
Order Reports By Integration Type
Order reports are only relevant to Fully Hosted and Custom integrations.
Only Fully Hosted and Custom integrations generate Forage Order objects. Use any of the other report types if you're building with an SDK.

An order report includes a list of Forage Orders created during the provided reporting period.

If the status of an Order is not succeeded or failed, then some of the object response fields return null, as indicated in the table below.

The results field of the response to requests to /reporting/orders/ returns an array of objects. Each object contains the following fields:

Property	Type	Description
`ref`	string	A unique reference hash for the Forage `Order` object.
`status`	string	The status of the order in the Forage lifecycle. One of: - `canceled` - `draft` - `failed` - `processing` - `succeeded`
`snap_eligible_total`	number	The SNAP-only eligible portion of the order cost in USD.
`ebt_cash_eligible_total`	number	The EBT Cash-only eligible portion of the order cost in USD.
`remaining_total`	number	The portion of the order total in USD that is not SNAP or EBT Cash eligible. This amount must be charged to a credit or debit card.
`sales_tax_applied` _The value of this field is `null` if the `status` is not `succeeded` or `failed`_	number	The amount of sales tax that Forage added to the order total, calculated after the customer distributed tender across payment methods. This value is always `0` for Custom integrations. Forage only calculates taxes for Fully Hosted integrations. If the value is nonzero, then some of the `ebt_cash_paid` or `credit_debit_paid` covered taxes. Per FNS regulations, `snap_paid` is tax-exempt. The sum of (`snap_paid`, `ebt_cash_paid`, `credit_debit_paid`) should always equal the sum of (`sales_tax_applied`, `snap_eligible_total`, `remaining_total`).
`snap_paid` _The value of this field is `null` if the `status` is not `succeeded` or `failed`_	number	The portion of the order cost in USD that the customer paid for with SNAP benefits.
`ebt_cash_paid` _The value of this field is `null` if the `status` is not `succeeded` or `failed`_	number	The portion of the order cost in USD that the customer paid for with EBT Cash benefits.
`credit_debit_paid` _The value of this field is `null` if the `status` is not `succeeded` or `failed`_	number	The portion of the order cost in USD that the customer paid for with credit/debit card.
`merchant_fns_number`	string	The FNS number of the merchant that created this order.
`success_date`	ISO 8601 date-time string	A UTC-8 timestamp of when all `OrderPayments` associated with the `Order` are successfully processed, represented as an ISO 8601 date-time string.
`created`	ISO 8601 date-time string	A UTC-8 timestamp of when the `Order` was created, represented as an ISO 8601 date-time string.
`payments`	array of strings	An array of the unique reference hashes for any Forage `OrderPayments` associated with this `Order`.
`refunds`	array of strings	An array of the unique reference hashes for any Forage `OrderRefunds` associated with the `Order`.
`psp_customer_id`	string	The third-party credit/debit payment processor's unique identifier for the customer. The value of this field is `null` if the `Order` was created via a POST to `/capture/`.
`external_order_id`	string	A unique identifier for the order as created by the merchant or platform (not Forage). When a merchant or platform passes this order ID to Forage, it persists in each Forage transaction related to the `Order`. This field enables merchants to map order IDs in their system to corresponding Forage `Order` IDs.
`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.

Example request

📘
FIlter For Successful Orders
If you add the status query param and pass succeeded as the value, then the start_date and end_date params refer to the order's success_date, rather than its created value. The status filter has no effect if any other value is applied or if excluded from the request.
Check out the /reporting/orders/ reference docs for details.

curl --request GET \
     --url 'https://api.sandbox.joinforage.app/reporting/orders/?start_date=2021-01-31&end_date=2021-02-28&limit=1&status=succeeded' \
     --header 'Authorization: Bearer <authentication_token>' \
     --header 'Merchant-Account: <merchant_account>' \
     --header 'accept: application/json'

Payout Reports

/reporting/payouts/

A payout is a scheduled funds disbursement from Forage to a merchant. A payout accounts for all transactions, both purchases and refunds, during the scheduled time period.

A Payout Report includes a list of payouts that occurred during the provided time period.

The results field of the response to requests to /reporting/payouts/ returns an array of objects with the following fields:

Column name	Type	Description	Example value
`merchant_payout_id`	string	A unique 10-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 10-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 10-character 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_void_purchases`	number	The total amount in USD refunded to customers due to a voided purchase initiated by Forage or the server.	`1.12`
`total_void_refunds`	number	The total amount in USD debited from customers due to a voided refund initiated by Forage or the server.	`0.22`
`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`

Example request

curl --request GET \
     --url 'https://api.sandbox.joinforage.app/reporting/payouts/?start_date=2021-01-31&end_date=2021-02-28&limit=1' \
     --header 'Authorization: Bearer <authentication_token>' \
     --header 'Merchant-Account: <merchant_account>' \
     --header 'accept: application/json'

Payout Transaction Reports

/reporting/payouts/{payout_id}/transactions/

A Payout Transaction Report includes a list of all transactions associated with the provided payout_id.

Forage defines a transaction as any financial operation that triggers a flow of funds, including both EBT purchases and EBT refunds. Credit and debit card transactions are included in the report if the transaction occurred via a Fully Hosted integration, but Forage is never involved in the settlement flow for credit/debit. That falls to the credit/debit PSP, so balance your credit/debit accounting against the PSP's ledger.

👉 See our Transaction types guide for details on credit/debit flow.

The results field of the response to requests to /reporting/payouts/{payout_id}/transactions/ returns an array of objects with the following fields:

Column name	Type	Description	Example value
`merchant_id`	string	A 10-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` - `Credit_Debit` - `Payfac_Credit_Debit` - `HSA` - `FSA` If the `transaction_type` is one of the following, `payment_method` will be `\"\"`: - `Positive_adjustment` - `Negative_adjustment` - `Balance_Inquiry_Fee` - `Refund_Processing_Fee`	`SNAP`
`transaction_type`	string	The type of the transaction. Must be one of the following: - `Purchase` - `Purchase_With_Cash_Back` - `Refund` - `Withdrawal` - `Chargeback` - `Void_Purchase` - `Void_Refund` - `Negative_adjustment` - `Positive_adjustment` - `Balance_Inquiry_Fee` - `Refund_Processing_Fee` 👉 See our Transaction types guide for details on credit/debit flow.	`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 10-character identifier for the transaction's merchant payout.	`9f7734298d`
`platform_payout_id`	string	A unique 10-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 10-character 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`

Example request

curl --request GET \
     --url 'https://api.sandbox.joinforage.app/reporting/payouts/27/transactions/?start_date=2021-01-31&end_date=2021-02-28&limit=1' \
     --header 'Authorization: Bearer <authentication_token>' \
     --header 'Merchant-Account: <merchant_account>' \
     --header 'accept: application/json'

Transaction Reports

/reporting/transactions/

A Transaction Report includes a list of all transactions that Forage recorded between the provided start_date and end_date.

Forage defines a transaction as any financial operation that triggers a flow of funds, including both EBT purchases and EBT refunds. A Transaction Report is useful for reconciling your accounting books against the Forage ledger. The fee field can help finance teams reconcile the payouts received from Forage.

Credit and debit card transactions are included in the report if the transaction occurred via a Fully Hosted integration, but Forage is never involved in the settlement flow for credit/debit. That falls to the credit/debit PSP, so balance your credit/debit accounting against the PSP's ledger.

The results field of the response to requests to /reporting/transactions/ returns an array of objects with the following fields:

Column name	Type	Description	Example value
`merchant_id`	string	A 10-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` - `Credit_Debit` - `Payfac_Credit_Debit` - `HSA` - `FSA` If the `transaction_type` is one of the following, `payment_method` will be `\"\"`: - `Positive_adjustment` - `Negative_adjustment` - `Balance_Inquiry_Fee` - `Refund_Processing_Fee`	`SNAP`
`transaction_type`	string	The type of the transaction. Must be one of the following: - `Purchase` - `Purchase_With_Cash_Back` - `Refund` - `Withdrawal` - `Chargeback` - `Void_Purchase` - `Void_Refund` - `Negative_adjustment` - `Positive_adjustment` - `Balance_Inquiry_Fee` - `Refund_Processing_Fee`	`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`

Example request

curl --request GET \
     --url 'https://api.sandbox.joinforage.app/reporting/transactions/?start_date=2021-01-31&end_date=2021-02-28&limit=1' \
     --header 'Authorization: Bearer <authentication_token>' \
     --header 'Merchant-Account: <merchant_account>' \
     --header 'accept: application/json'