HomeGuidesReference
Log In
Reference

Reports

You can use the Forage API to retrieve data about your EBT SNAP business.

With the /reporting/ endpoints, you can:

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:

PropertyTypeDescription
nextstringA 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.
previousstringA 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.
resultsarrayAn 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 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:

PropertyTypeDescription
refstringA unique reference hash for the Forage Order object.
statusstringThe status of the order in the Forage lifecycle. One of:

- canceled

- draft
- failed
- processing
- succeeded
snap_eligible_totalnumberThe SNAP-only eligible portion of the order cost in USD.
ebt_cash_eligible_totalnumberThe EBT Cash-only eligible portion of the order cost in USD.
remaining_totalnumberThe 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
numberThe 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
numberThe 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
numberThe 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
numberThe portion of the order cost in USD that the customer paid for with credit/debit card.
merchant_fns_numberstringThe FNS number of the merchant that created this order.
success_dateISO 8601 date-time stringA UTC-8 timestamp of when all OrderPayments associated with the Order are successfully processed, represented as an ISO 8601 date-time string.
createdISO 8601 date-time stringA UTC-8 timestamp of when the Order was created, represented as an ISO 8601 date-time string.
paymentsarray of stringsAn array of the unique reference hashes for any Forage OrderPayments associated with this Order.
refundsarray of stringsAn array of the unique reference hashes for any Forage OrderRefunds associated with the Order.
psp_customer_idstringThe 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_sessions/.
external_order_idstringA 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_idstringA 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

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 Summary 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 nameTypeDescriptionExample value
merchant_payout_idstringA 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_idstringA 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_idstringOne 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_idstringA merchant’s unique FNS number.

This value is blank if the settlement reflects a platform instead of a merchant payout.
1811145
payout_issued_datestringA date-stamp of when the payout was created.06/18/2024
expected_deposit_datestringA 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_purchasesnumberThe total amount in USD of all of the purchases included in this payout.180.98
total_refundsnumberThe total amount in USD of all of the refunds included in this payout.0.00
total_void_purchasesnumberThe total amount in USD refunded to customers due to a voided purchase initiated by Forage or the server.1.12
total_void_refundsnumberThe total amount in USD debited from customers due to a voided refund initiated by Forage or the server.0.22
total_chargebacksnumberThe 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_adjustmentsnumberIf 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_adjustmentsnumberIf 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_settlementnumberThe 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_settlementnumberThe 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_refstringA 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.

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

Column nameTypeDescriptionExample value
merchant_idstringA 10-character identifier for a merchant, provided by Forage.a0040a0020
fns_idstringA merchant’s unique FNS number.1234567
payout_issued_datestringA date-stamp of when the payout was created.06/18/2024
expected_deposit_datestringA 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_datestringThe date and time of the transaction, formatted as an ISO 8601 string in the UTC timezone.2024-11-04T14:00:00Z
payment_methodstringThe 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_typestringThe 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_amountnumberThe total amount in USD charged, voided, or refunded to the customer.28.15
merchant_net_settlementnumberThe net amount sent to the merchant, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions.27.03
platform_net_settlementnumberIf 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_idstringA unique 10-character identifier for the transaction's merchant payout.9f7734298d
platform_payout_idstringA 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_idstringFor 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_idstringA 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_idstringA unique 10-character identifier for the payment transaction.4be98347f6
refund_idstringIf the transaction_type is Refund, a unique identifier for the refund transaction.

This value is blank for all other transaction types.
cbe72b8320
chargeback_idstringIf 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_refstringA unique reference hash for the bank account that received the funds settlement for this payment.20b0b0123
external_location_idstringA 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
descriptionstringA 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 nameTypeDescriptionExample value
merchant_idstringA 10-character identifier for a merchant, provided by Forage.a0i404a0020
fns_idstringA merchant’s unique FNS number.1234567
recorded_datestringThe date and time of the transaction, formatted as an ISO 8601 string in the UTC timezone.2024-11-04T14:00:00Z
payment_methodstringThe 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_typestringThe 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_amountnumberThe total amount in USD charged, voided, or refunded to the customer.28.15
merchant_net_settlementnumberThe net amount sent to the merchant, equal to the sum of purchases minus refunds, chargebacks, fees, and any other deductions.27.03
platform_net_settlementnumberIf 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_idstringFor 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_idstringA 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_idstringA unique identifier for the payment transaction.4be98347f6
refund_idstringIf the transaction_type is Refund, a unique identifier for the refund transaction.

This value is blank for all other transaction types.
cbe72b8320
chargeback_idstringIf 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_refstringA unique reference hash for the bank account that received funds settlement for this payment.20b0b0123
external_location_idstringA 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
descriptionstringA 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'