Reports

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 report: 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 the report:

start_date | date

required

The date that the reporting period starts, represented as an ISO 8601 date string. All transactions on this date are included in the response.

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

required

The date that the reporting period ends, represented as an ISO 8601 date string. All transactions on this date are included in the response.

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 results to include in the results array of each paginated response. Not to exceed 50. Forage reduces any exceeding values to 50. Defaults to 20.

offset | integer

The starting point for the first returned page of results. For example, if the offset is 50, then the results in the initial response include the 51st object up to the limit.

If the offset value exceeds the total number of results, then the API responds with an empty results field instead of a 400.

Report object

Example Order Report

{
  "count": 120,
  "next": "http://api.sandbox.joinforage.app/reporting/transactions/?limit=1&offset=50&start_date=2022-03-22&end_date=2022-03-24",
  "previous": "http://api.sandbox.joinforage.app/reporting/transactions/?limit=1&offset=0&start_date=2022-03-22&end_date=2022-03-24",
  "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",
      "success_date": "2021-06-16T00:11:50.000000Z-07:00",
      "created": "2021-06-15T00: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:

Report types

Order Reports

/reporting/orders/

✅

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 with the following fields:

Example request

✅

How to 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&offset=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:

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&offset=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.

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

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&offset=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:

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&offset=1' \
     --header 'Authorization: Bearer <authentication_token>' \
     --header 'Merchant-Account: <merchant_account>' \
     --header 'accept: application/json'