HomeGuidesReference
Log In
Reference

Changelog

This page lists all the changes for each supported version of the Forage API. Versions are named by their release date in the YYYY-MM-DD format.

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

Reference

August 4, 2025

The following changes were made:

💡 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 (""):
      • Positive_adjustment
      • Negative_adjustment
      • Balance_Inquiry_Fee
      • Refund_Processing_Fee

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

  • In the Payout Transaction Report, “Payout” now refers to an ACH, rather than a daily aggregation.
  • The query parameter payout_id now represents an ACH (Forage PayoutGroup) rather than a daily aggregation (Forage PlannedDisbursement). See https://{environment}.joinforage.app/reporting/payouts/{payout_id}/transactions/
  • API response field names has changed for a few fields. merchant_payout_id and platform_payout_id now refer to a single ACH.
  • For the Transaction Report response, API response field names have changed. See below.

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

February 15, 2024

The following changes were made:

  • Added release info for v2024-02-15.

v2024-02-15

January 8, 2024

The following changes were made:

  • Added release info for v2024-01-08.

v2024-01-08

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

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

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.