September 19, 2025

We have bumped the default API version to the newest version (v2025-08-04). No action is needed; everyone is now on this version by default.

Summary of content changes

The following guides and API reference have been updated for this new version:

Guides

(FHC) Quickstart: Removed redundant totals from session request examples.
Enable HSA/FSA Payments: New Step 4: Receipt requirements (IRS fields + example).
Classify Your Product Catalog: New section: Private label items need Forage manual review.
Understanding Transaction Type: Added HSA and FSA payment methods.
(Android) Quickstart: Added PaymentSheet docs for HSA/FSA tokenization.

Reference

Forage JS Errors: Added Payment Sheet error docs.
Create a PaymentMethod: Expanded Merchant-Account header rules by payment type.
Retrieve a Transaction Report: Renamed "Log" → "Report."
Tokenize an EBT Card: Renamed "Tokenize a Card" → "Tokenize an EBT Card."

August 4, 2025

The following changes were made:

Added release info for v2025-08-04.
Added ProductData Tender Breakdown Fields for release v2025-01-14.
Added Refund By Product Endpoint for release v2025-01-14.

💡 The current default version is v2025-01-14.

v2025-08-04

1. Order and Session Schema Updates

Endpoint: PATCH /orders/{order_ref}
Endpoint: POST /sessions/

Field Changes

Deleted Fields
- snap_total
- ebt_cash_total
- remaining_total

These fields were removed from the Order and SessionRequest schemas to reduce redundancy and simplify session and order creation logic. Their values can now be derived from the product_list object and no longer need to be passed directly.

Descriptions and required field references were updated accordingly.

January 14, 2025

The following changes were made:

Added release info for v2025-01-14.

v2025-01-14

To improve reporting accuracy and transparency, we’ve updated several API endpoints to include new fields and surface previously hidden transaction adjustments. These changes ensure better alignment of transaction data across the Forage Dashboard, API, and CSV outputs.

1. Payout Summary

Endpoint: GET /reporting/payouts/

Field Changes

New Fields:
- total_void_purchases: The total amount in USD refunded to customers due to a voided purchase initiated by Forage or the server.
- total_void_refunds: The total amount in USD debited from customers due to a voided refund initiated by Forage or the server.

2. Payout Transaction & Transaction Report

Endpoint: GET /reporting/payouts/{payout_id}/transactions/

Endpoint: GET /reporting/transactions/

Field Changes

Modified Fields:
- transaction_type: Updated to provide more meaningful representations.
  - Reports now include:
    - Positive_adjustment: Indicates positive transaction corrections.
    - Negative_adjustment: Indicates negative transaction corrections previously hidden from reports.
    - Balance_Inquiry_Fee: Indicates fee charged for a Balance Inquiry
    - Refund_Processing_Fee: Indicates fee charged for processing a refund
  - Changed existing values, moving the tender information ("payment method") portion to the new payment_method field. For example, SNAP_Purchase is now Purchase.
New Field:
- payment_method: Displays the type of payment method used. Supported values include:
  - Credit_Debit
  - EBT_Cash
  - FSA
  - HSA
  - Payfac_Credit_Debit
  - SNAP
- If transaction_type is one of the following, payment_method will be an empty string (""):

3. ProductData Tender Breakdown Fields

💡
Post-Release Addition
The following changes were added to version v2025-01-14 after its initial release.

Endpoint: POST /sessions/

Field Changes

New Fields
- snap_amount
- cash_amount
- credit_debit_amount
- tax_collected

These fields show how much of each product in a session was paid using SNAP, EBT Cash, credit/debit, and taxes collected.

⚠️ This endpoint is only used in Fully Hosted Checkout implementations and cannot be used elsewhere.

4. Refund by Product Endpoint

💡
Post-Release Addition
The following changes were added to version v2025-01-14 after its initial release.

Endpoint: POST /orders/{order_ref}/refund_by_product/

Description

This new endpoint allows merchants to issue item-level refunds by specifying the product ID and quantity.

Forage calculates how much should be refunded to each original tender type
Refund objects are created immediately

⚠️ This endpoint is only used in Fully Hosted Checkout implementations and cannot be used elsewhere

August 30, 2024

The following changes were made:

Added release info for v2024-08-30.

v2024-08-30

1. Payout Summary

The Payout Summary API now displays ACH disbursement details instead of daily aggregations. Each API result corresponds directly to an ACH transfer to the customer’s bank account.

For Daily Settlements: The API response remains largely unchanged, as daily disbursements continue to match previous daily aggregations.
For Monthly Settlements: Previously, the report displayed daily aggregations, even if only one ACH was made for the month. The updated report now consolidates these into a single entry per ACH, reflecting the total amount disbursed for the month.

Field Changes for Payout Summary

Deleted Fields
- Deleted merchant_name.
- Deleted tenant_name.
- Deleted external_location_id.
Renamed Fields
- Renamed merchant_fns_number to fns_id.
- Consolidated merchant_settlement_date and platform_settlement_date into the field payout_issued_date.
- Renamed the field fee to forage_fee.
New Fields
- Added merchant_id - A ten character identifier for a merchant, provided by Forage. We now display this instead of the merchant name.
- Added expected_deposit_date - A date-stamp of when Forage expects the payout to be deposited.
- Added total_positive_adjustments - If any, the total arbitrary amount in USD that has been added to the settlement.
- Added total_negative_adjustments - If any, the total arbitrary amount in USD that has been deducted from the settlement.

2. Payout Transaction Report

Field Changes for Payout Transaction Report and Transaction Report

Deleted Fields
- Deleted retrieval_ref.
- Deleted zipcode.
- Deleted state_code.
Renamed Fields
- Renamed order_ref to order_id
- Renamed payment_ref to payment_id
- Renamed refund_ref to refund_id
- Renamed merchant_fns_number to fns_id
- Consolidated merchant_settlement_date and platform_settlement_date into payout_issued_date.
- Renamed gross_merchandise_value to transaction_amount
- Renamed fee to forage_fee
- Renamed payout_id to merchant_payout_id / platform_payout_id. A transaction can now be included in both a merchant payout and a platform payout when platform settlement is enabled (for example, part of the funds are allocated to the merchant and part to the platform).
New Fields
- Added merchant_id - A ten character identifier for a merchant, provided by Forage. We now display this instead of the merchant name.
- Added expected_deposit_date - A date-stamp of when Forage expects the payout to be deposited.
- Added chargeback_id - A unique ID for the chargeback transaction. Used if the transaction_type is Chargeback.

May 7, 2024

The following changes were made:

Added release info for v2024-05-07.

v2024-05-07

All timestamp values in API response objects are now returned in UTC.

March 5, 2024

The following changes were made:

Added release info for v2024-03-05.

v2024-03-05

Updated the Create a Custom Payment Capture Session endpoint to accept a payment_details object instead of snap_total or ebt_cash_total parameters. This change allows Forage to automatically create OrderPayments for the Capture Session.
Added a PATCH endpoint to Update an OrderPayment.

February 15, 2024

The following changes were made:

Added release info for v2024-02-15.

v2024-02-15

Changed the reporting endpoints to use cursor pagination instead of offset pagination.

January 8, 2024

The following changes were made:

Added release info for v2024-01-08.

v2024-01-08

Updated the Create a PaymentRefund and Create a refund for part of an Order endpoints to return the refund response synchronously with receipt data.

May 15, 2023

The following changes were made:

Added release info for v2023-05-15.

v2023-05-15

1. customer_id Parameter

Introduced a new customer_id parameter, required for balance checks.
Use customer_id to share a merchant-specific customer ID with Forage.
This parameter enables merchants to link their own customer identifiers with Forage systems.

POST Endpoints Supporting `customer_id`

Create a Fully Hosted Checkout session: /sessions/
Create a Custom Checkout session: /capture_sessions/
Create a PaymentMethod: /payment_methods/
Create an OrderPayment: /orders/{order_ref}/payments/
Create a Payment: /payments/

GET Responses

The above endpoints return customer_id if it was included in the request.

Impact on Balance Checks

If you want Forage to perform a balance check, you must pass the customer_id parameter in the request.

2. psp_customer_id Parameter

Introduced psp_customer_id to replace the original customer_id parameter.
Use psp_customer_id to share a credit/debit TPP customer ID with Forage.
This parameter is specific to payment processing with third-party providers (TPPs).

3. external_order_id Parameter

Added an external_order_id to enable merchants to match their own order IDs with Forage order IDs.

POST Endpoints Supporting `external_order_id`

Create a Fully Hosted Checkout session: /sessions/
Create a Custom Checkout session: /capture_sessions/
Create a Payment: /payments/
Create an OrderPayment: /orders/{order_ref}/payments/
Create an OrderRefund: /orders/{order_ref}/refunds/
Create a PaymentRefund: /payments/{payment_ref}/refunds/

GET Responses

The above endpoints and /reporting endpoints return external_order_id, if available.

Initial API Release (unversioned)

Introduced split tender support for SNAP, EBT Cash, and credit/debit cards.