Retrieve all OrderRefunds for an Order

get https://{environment}.joinforage.app/api/orders/{order_ref}/refunds/

A GET request to /orders/{order_ref}/refunds/ retrieves all OrderRefunds associated with the provided order_ref.

On success, the API responds with an array of OrderRefunds.

Path Params

order_ref

string

required

A unique reference hash for the Forage Order object, returned when the order’s parent Session was created.

Headers

Authorization

string

required

An OAuth 2.0 authentication token that validates the request. Send a POST to the /o/token/ endpoint to generate an authentication token. Pass the token in this header after the word Bearer and a whitespace, for example Bearer sandbox_sZawPSUSm9eetx8LrfBbJlzUZS3zWD.

Merchant-Account

string

required

A unique merchant ID that Forage provides during onboarding, as in 123ab45c67. The Merchant ID can be found in the Forage sandbox or production dashboard.

API-Version

string

The Forage version, represented as a string with the format of a YYYY-MM-DD date.

If not specified in the request header, then the version defaults to the value set in the Forage dashboard.

Responses

Response body

array of objects

object

payment

string

required

A unique reference hash for the Forage OrderPayment to be refunded, returned when the OrderPayment was created.

amount

number

required

The amount to be refunded in USD. Does not need to equal the amount field of the OrderPayment, if a partial refund. Precision is supported to the penny.

The minimum amount that can be refunded is 0.01.

reason

string

required

A string that describes why the refund is happening.

metadata

object

required

A required object containing merchant-defined key-value pairs to provide additional context for the payment.

Merchants should use this field to store reference information relevant to the transaction (for example, order details, system identifiers, or tracking data). This helps link the payment to records within their system.

Pass an empty object ({}) if no additional information is available.

⚠️
Do not include personally identifiable information (PII) such as names, emails, or payment details.

Has additional fields

merchant_fixed_settlement

number

The fixed amount in USD that should be restored to the merchant from EBT Cash payments prior to splitting by the platform_fee. Precision is supported to the penny.

platform_fixed_settlement

number

The fixed amount in USD that should be restored to the platform from EBT Cash payments prior to splitting by the platform_fee. Precision is supported to the penny.

external_order_id

string

length ≤ 64

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.

You must build with Forage Version 2023-05-15 or later to use external_order_id. Either pass 2023-05-15 as the API-Version header on a per request basis, or set the version for all requests in the Forage dashboard.

ref

string

A unique reference hash for the OrderRefund.

order

string

The unique reference hash for the parent Forage Order.

funding_type

string

A string that represents the type of tender. One of:

benefit
credit_tpp
ebt_snap
ebt_cash

benefit credit_tpp ebt_snap ebt_cash

status

string

The status of the OrderRefund. One of:

canceled: The OrderRefund has been voided and can't be changed.
failed: The OrderRefund failed to process. Check the receipt.message field for a description of the error.
processing: The outcome of the OrderRefund is pending, and the refund can't be modified. This status is not returned if you’re using Forage version 2024-01-08 or higher.
succeeded: The OrderRefund has been successfully processed and will be included in settlement.

canceled failed processing succeeded

last_processing_error

object

The code and message values corresponding to the most recent Payments API error. Always null when the Payment is created.

Has additional fields

created

date-time

A UTC timestamp that indicates when this object was created, represented as an ISO 8601 date-time string.

updated

date-time

A UTC timestamp that indicates when this object was last modified, represented as an ISO 8601 date-time string.

receipt

object

Most of the information that you're required to display to the customer, according to FNS regulations.

This field is null if the data that populates the receipt is not yet available.

The total amount paid by the customer is snap_amount + ebt_cash_amount + other_amount + sales_tax_applied. This amount will be settled with the merchant after applying Forage's fees.

tpp_lookup_id

string

The unique identifier from the relevant credit TPP or null for EBT refunds. For Stripe integrations, this is the id of the Refund object on Stripe's backend.

Language

Credentials

OAuth2

URL

Request


xxxxxxxxxx
1
curl --request GET \
2
    --url https://api.sandbox.joinforage.app/api/orders/93410bcaff/refunds/ \
3
    --header 'Authorization: Bearer sandbox_sZawPSUSm9eetx8LrfBbJlzUZS3zWD' \
4
    --header 'Merchant-Account: 123ab45c67' \
5
    --header 'accept: application/json' \
6

Choose an example:

application/json

200OK - Success

⚠️Do not include personally identifiable information (PII) such as names, emails, or payment details.

400Bad request - The request was not accepted because of an error in the request body or path.

401Unauthorized

404Not Found - The requested resource was not found.

429Too Many Requests

500Internal Server Error

⚠️
Do not include personally identifiable information (PII) such as names, emails, or payment details.