Sign in

v1

latestOpenAPI 3.0.02026-07-244352379.2 KB
Orders

Update an Order

A PATCH request to /orders/{order_ref}/ modifies the indicated Order object.

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

On success, the API responds with the updated Order.

To modify payments associated with an Order, send a request to Update an OrderPayment instead.

patch/api/orders/{order_ref}/

Headers

Authorizationstring 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 <api_key>.

Request body

platform_feenumber

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.

is_deliveryboolean

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

success_redirect_urlstring

The URL to redirect your customer to if the Order is completed successfully.

cancel_redirect_urlstring

The URL to redirect your customer to if the order is canceled.

supported_benefitsstring[]

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

The third-party payment processor's unique identifier for the customer. An optional field passed in anticipation of a customer applying a credit/debit card to an Order balance.

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

⚠️ 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

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.

is_commercial_shippingboolean

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

external_location_idstring

A unique identifier, provided by the merchant or platform (not Forage), that indicates the physical fulfillment location for the order. For example, this field could specify which location of a grocery store chain fulfilled an order.

Example request

{
  "external_location_id": "6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9"
}

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