Update an Order

patch

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

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.

Path Params

order_ref

string

required

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

Body Params

Pass the following request body to update an Order.

product_list

array of objects

A list of products that a customer has in their cart at checkout. If there are no taxes applied to any of the products, this field can be empty. This field can only be updated for an Order that is the outcome of a Fully Hosted Session. The product_list is null in the case of an Order created via a Custom Payment Capture Session.

product_list

platform_fee

number

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.

delivery_address

object

⚠️ Exception: If the purchase is made in-store via a POS Terminal, then a delivery_address is not required when creating a Payment.

The address for delivery or pickup of the Order. Per FNS regulations, this value must always be provided. If the Order is for pickup, then use the merchant address.

is_delivery

boolean

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

success_redirect_url

string

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

cancel_redirect_url

string

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

supported_benefits

array of strings

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

supported_benefits

psp_customer_id

string

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_id

string

length ≤ 64

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

is_commercial_shipping

boolean

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

external_location_id

string

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.

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

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

200OK - Success

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

401Unauthorized

403Forbidden

404Not Found - The requested resource was not found.

409Conflict

429Too Many Requests

500Internal Server Error