You can use the Forage API to retrieve data about your EBT SNAP business.
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
start_date
| daterequired
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
end_date
| daterequired
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
limit
| integerThe 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
offset
| integerThe 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 51
st 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
Report
objectExample Order Report
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:
Property | Type | Description |
---|---|---|
count | integer | The total number of results between the provided start_date and end_date . Without pagination, this is the number of objects that would be returned at once in the results array.Use the next and previous values to page through the results. |
next | string | The URL to send a GET to in order to retrieve the next page of results.The value is null if the current page is the last of the result set. |
previous | string | The URL to send a GET to in order to retrieve the previous page of results.The value is null if the current page is the first of the result set. |
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 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:
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 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 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_sessions/ . |
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. |
Example request
How to filter for successful orders
If you add the
status
query param and passsucceeded
as the value, then thestart_date
andend_date
params refer to the order’ssuccess_date
, rather than itscreated
value. Thestatus
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:
Property | Type | Description |
---|---|---|
payout_id | integer | A unique identifier for the payout. |
merchant_name | string | The name of the merchant that received this payout. |
tenant_name | string | The name of the platform that the merchant that received this payout sells through, if applicable. |
merchant_fns_number | string | The FNS number of the merchant that received this payout. |
transaction_date | ISO 8601 date-time string | A timestamp of when the transactions included in this payout occurred, represented as an ISO 8601 date-time string. |
settlement_date | ISO 8601 date-time string | A timestamp of when this payout was settled to the merchant’s account, represented as an ISO 8601 date-time string. |
total_purchases | number | The total amount in USD of all of the purchases included in this payout. |
total_refunds | number | The total amount in USD of all of the refunds included in this payout. |
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. |
fee | number | The sum of Forage fees in USD for all transactions included in this payout. |
merchant_net_settlement | number | The gross value of the merchandise involved in the payout, minus the Forage fee .For merchants processing via a platform, this value is the gross merchandise value minus both fee and platform_net_settlement . |
platform_net_settlement | number | The gross value of the merchandise involved in the payout, minus the Forage fee and merchant_net_settlement .This value is 0 if the merchant does not process via a platform |
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:
Property | Type | Description |
---|---|---|
order_ref | string | A unique reference hash identifier for the Forage Order associated with this transaction, if applicable.This value is only returned for Fully Hosted and Custom integrations. |
payment_ref | string | A unique reference hash identifier for the Forage Payment or OrderPayment associated with this transaction. |
retrieval_ref | string | A unique, 12-digit reference hash identifier for the transaction that you can use to look up the original object on Forage’s backend. The first two characters identify the transaction type: - PA identifies a payment- RE identifies a refundThe last ten characters are the Forage transaction ref . |
merchant_fns_number | string | The FNS number of the merchant that received the payout including this transaction. |
transaction_type | string | The type of the transaction. One of: - Credit_Debit_Chargeback - Credit_Debit_Purchase - Credit_Debit_Refund - Credit_Debit_Void_Purchase - Credit_Debit_Void_Refund - EBT_Cash_Chargeback - EBT_Cash_Purchase - EBT_Cash_Refund - EBT_Cash_Void_Purchase - EBT_Cash_Void_Refund - SNAP_Chargeback - SNAP_Purchase - SNAP_Refund - SNAP_Void_Purchase - SNAP_Void_Refund The Credit_Debit_ transaction type is only returned if a transaction occurred via a Fully Hosted integration. |
description | string | A description of the transaction. |
recorded_date | ISO 8601 date-time string | A timestamp of when the transaction successfully processed, represented as an ISO 8601 date-time string. |
gross_merchandise_value | number | The total amount in USD charged to the customer. |
fee | number | The total amount in USD that Forage charged to process this transaction. |
merchant_net_settlement | number | The gross value of the merchandise involved in the payout, minus the Forage fee .For merchants processing via a platform, this value is the gross merchandise value minus both fee and platform_net_settlement . |
platform_net_settlement | number | The gross value of the merchandise involved in the payout less the Forage fee and merchant_net_settlement .This value is 0 if the merchant does not process via a platform. |
zipcode | string | The zip code of the delivery/pickup address for the order associated with this transaction. |
state_code | string | The two-letter abbreviation for the US state of the delivery/pickup address for the order associated with this transaction. |
settlement_date | ISO 8601 date-time string | A timestamp of when the transaction is or was scheduled for settlement, represented as an ISO 8601 date-time string. |
payout_id | integer | A unique identifier for the payout that this transaction is associated with. This field is null until Forage disperses the payout. |
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. New in version 2023-05-15. |
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:
Property | Type | Description |
---|---|---|
order_ref | string | A unique reference hash identifier for the Forage Order associated with this transaction, if applicable.This value is only returned for Fully Hosted and Custom integrations. |
payment_ref | string | A unique reference hash identifier for the Forage Payment or OrderPayment associated with this transaction. |
retrieval_ref | string | A unique, 12-digit reference hash identifier for the transaction that you can use to look up the original object on Forage’s backend. The first two characters identify the transaction type: - PA identifies a payment- RE identifies a refundThe last ten characters are the Forage transaction ref . |
merchant_fns_number | string | The FNS number of the merchant that received the payout including this transaction. |
transaction_type | string | The type of the transaction. One of: - Credit_Debit_Chargeback - Credit_Debit_Purchase - Credit_Debit_Refund - Credit_Debit_Void_Purchase - Credit_Debit_Void_Refund - EBT_Cash_Chargeback - EBT_Cash_Purchase - EBT_Cash_Refund - EBT_Cash_Void_Purchase - EBT_Cash_Void_Refund - SNAP_Chargeback - SNAP_Purchase - SNAP_Refund - SNAP_Void_Purchase - SNAP_Void_Refund The Credit_Debit_ transaction type is only returned if a transaction occurred via a Fully Hosted integration. |
description | string | A description of the transaction. |
recorded_date | ISO 8601 date-time string | A timestamp of when the transaction successfully processed, represented as an ISO 8601 date-time string. |
gross_merchandise_value | number | The total amount in USD charged to the customer. |
fee | number | The total amount in USD that Forage charged to process this transaction. |
merchant_net_settlement | number | The gross value of the merchandise involved in the payout, minus the Forage fee .For merchants processing via a platform, this value is the gross merchandise value minus both fee and platform_net_settlement . |
platform_net_settlement | number | The gross value of the merchandise involved in the payout less the Forage fee and merchant_net_settlement .This value is 0 if the merchant does not process via a platform. |
zipcode | string | The zip code of the delivery/pickup address for the order associated with this transaction. |
state_code | string | The two-letter abbreviation for the US state of the delivery/pickup address for the order associated with this transaction. |
settlement_date | ISO 8601 date-time string | A timestamp of when the transaction is or was scheduled for settlement, represented as an ISO 8601 date-time string. |
payout_id | integer | A unique identifier for the payout that this transaction is associated with. This field is null until Forage disperses the payout. |
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. New in version 2023-05-15. |
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'