v1

latestOpenAPI 3.0.02026-07-244352379.2 KB

Orders

Retrieve an Order

A GET request to /orders/{order_ref}/ retrieves the specified Order object.

The order_ref is the ref value that Forage returns in response to the request that created the order’s parent Session.

You can use this endpoint to request the transaction outcome from Forage after a customer completes a Fully Hosted or Custom Session.

get/api/orders/{order_ref}/

Headers

Authorizationstring required

An OAuth 2.0 bearer token that validates the request. You can use either a short-lived session token if the request is coming from the front-end, or an authentication token for server-side requests. Pass the token in this header after the word Bearer and a whitespace, for example Bearer <api_key>.

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": []
}