Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Order Refunds

Create a refund for an entire Order

⚠️ Refunding Entire Orders Must Be Server-Side

To keep your app secure, requests to refund an entire Order should only be generated on the server-side.

A POST request to /orders/{order_ref}/refund_all/ refunds an entire Order. It tells Forage’s servers to create an OrderRefund for every associated OrderPayment, and to refund all charges to their original payment methods, net any already processed refunds. This request has immediate financial side effects.

On success, the API responds with the original Order. The refunds field details a list of reference hashes, refund_refs, for all of the OrderRefunds that Forage created as part of the refund process.

If there are any OrderRefunds still processing when you send the POST, then the API returns a 400 until those refunds have resolved.

To retrieve information about a particular OrderRefund in the list, send a GET to /orders/{order_ref}/refunds/{refund_ref}/.

⚠️ Retrieving Refund Receipt Info

This endpoint does not return receipt information.

To retrieve transaction information to display to a customer, send periodic GET requests to /orders/{order_ref}/refunds/{refund_ref}/ for everyOrderRefund returned in the refunds field until the status of each is succeeded. Then, confirm that the receipt.balance.updated timestamp is no longer changing and retrieve the latest balance.

📘 Webhooks For Refund Status Updates

Forage sends a REFUND_STATUS_UPDATED webhook when the status of a refund changes. Check out the guide to Forage webhooks for instructions on how to listen for the event.

post/api/orders/{order_ref}/refund_all/

Request body

reasonstring required

A string that describes why the order is to be refunded.

metadataMetadataObject 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.

⚠️ Personally Identifiable Information

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

external_order_idstring

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.

Response

OK - Success

refstring required

A unique reference hash for the Forage Order object.

snap_totalstring currency required

The SNAP eligible portion of the order cost in USD, represented as a numeric string. Precision is supported to the penny.

ebt_cash_totalstring currency required

The portion of the Order total, in USD, that is EBT Cash eligible only, represented as a numeric string. Precision is supported to the penny.

remaining_totalstring currency

The portion of the Order total, in USD, that is neither SNAP eligible nor EBT Cash eligible, represented as a numeric string. This amount must be charged to a credit or debit card, with precision supported to the penny. This value is returned only for Fully Hosted Sessions and is not included if the Order was created using a POST request to /capture_sessions/.

platform_feestring decimal

An optional field, for use by a platform supporting multiple merchants, that indicates the percentage cut of each payment that the platform charges as a fee. Represented as a decimal string.

is_deliveryboolean required

Whether the order is for delivery or pickup. This information is required per FNS regulations. Defaults to false if not provided.

success_redirect_urlstring required

The URL to redirect your customer to if the order is completed successfully, passed in the original request to create a Session.

cancel_redirect_urlstring required

The URL to redirect your customer to if they cancel the order, passed in the original request to create a Session.

supported_benefitsstring[] required

A list that limits the types of payment methods that can be applied at checkout, including any or all of the values in: ["snap", "ebt_cash", "non_ebt"]. Use supported_benefits only if you want to restrict the possible payment method types. Omit this field in all other cases. For example, pass ["snap", "non_ebt"] if you want to accept SNAP and credit card payments only (excluding EBT Cash).

psp_customer_idstring nullable required

The third-party credit/debit payment processor's unique identifier for the customer. This value is returned as null if the Order was created via a POST to /capture_sessions/.

You must build with Forage Version 2023-05-15 or later to use psp_customer_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.

customer_idstring required

⚠️ If you’re integrating Forage with a POS Terminal, then do not use this param. It is only supported for online transactions.

A unique identifier for the end customer making the payment.

Forage automatically adds the customer_id to the Session's corresponding Order and OrderPayments.

This field helps Forage's servers more quickly identify the customer associated with the request. While customer_id is not technically required, if you omit it then requests could take longer to process. It is strongly recommended to pass customer_id.

If you're providing your internal customer ID, then we recommend that you hash the value before sending it on the payload.

Each customer should only have one unique customer_id. For example, if you create both a PaymentMethod and a Forage Session (Fully Hosted or Custom) or Payment (SDK) for the same customer, then the customer_id should be the same in both requests to ensure continuity of stored payment methods.

external_order_idstring required

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.

external_location_idstring nullable required

A unique identifier for the physical fulfillment location.

status'draft' | 'processing' | 'failed' | 'succeeded' | 'canceled' required

The status of the Order in the Forage lifecycle. One of:

  • canceled
  • draft (the status at the start, when a Session is created)
  • failed
  • processing
  • succeeded

If the value is failed, then inspect the associated Order Payments to determine the cause of the error.

paymentsstring[] required

An array of the unique reference hashes for any Forage OrderPayment objects associated with the Order.

refundsstring[] required

An array of the unique reference hashes for any Forage OrderRefund objects associated with the Order.

success_datestring date-time nullable required

A UTC timestamp of the date when the Order was successfully charged. This value is null if the status of the Order is not yet succeeded.

expires_atstring date-time nullable required

A UTC timestamp of when the Order will expire if it is not captured or canceled, set to 30 minutes from when the Order is created.

If the status of the Order is succeeded or canceled, then the expires_at value is null.

is_commercial_shippingboolean nullable required

Whether the order is to be shipped commercially. FNS uses this value in its database for statistics.

Example response

{
  "ref": "93410bcaff",
  "snap_total": "25.99",
  "ebt_cash_total": "5.99",
  "remaining_total": "10.99",
  "product_list": [],
  "platform_fee": "0.05",
  "is_delivery": true,
  "success_redirect_url": "https://www.your-app.com/status=SUCCEEDED",
  "cancel_redirect_url": "https://www.your-app.com/status=CANCELED",
  "supported_benefits": [
    "snap",
    "non_ebt"
  ],
  "psp_customer_id": "cus_AJ6yA7mRH34mJT",
  "status": "draft",
  "payments": [],
  "refunds": [],
  "success_date": "2021-06-16T00:11:50.000000Z",
  "receipt": {
    "balance": {
      "id": 12345
    }
  },
  "expires_at": "2021-06-16T00:41:50.000000Z",
  "previous_errors": []
}