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 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.

📘

Consult each endpoint's individual reference page for exact query params.

Not all endpoints accept a start_date and end_date, for example.

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:

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. Each object contains 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&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' \
     --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' \
     --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' \
     --header 'Authorization: Bearer <authentication_token>' \
     --header 'Merchant-Account: <merchant_account>' \
     --header 'accept: application/json'