--- title: "Update an Order" method: PATCH path: "/api/orders/{order_ref}/" tags: ["Orders"] --- # Update an Order `PATCH /api/orders/{order_ref}/` A `PATCH` request to `/orders/{order_ref}/` modifies the indicated [`Order` object](https://docs.joinforage.app/reference/orders#order-object). The `order_ref` is the `ref` value that Forage returns in response to the request that created the `Order`’s parent [`Session`](https://docs.joinforage.app/reference/forage-sessions). On success, the API responds with the updated `Order`. To modify payments associated with an `Order`, send a request to [Update an `OrderPayment`](https://docs.joinforage.app/reference/update-an-order-payment) instead. ## Headers - `Authorization` string, required ## Request body - OrderUpdateRequest — This object updates an order. - `product_list` ProductData[] — 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_. - `name` string, required — The name of the product. - `upc` string — The UPC of the product. - `gtin` string — The GTIN (Global Trade Item Number) of the product. - `unit_price` number, required — The unit price of the product. - `quantity` number — The quantity of the product. - `tax_rate` number — The tax rate for the product, represented as a decimal with at most six decimal places. A value of `0` indicates a tax rate of 0%, and a value of `1` indicates a tax rate of 100%. To set a 2% tax rate, for example, set the value to `0.02`. Use this field if the product is subject to only one tax rate. If multiple tax rates apply, for example both a state grocery tax and a sweetened beverage tax, then use the `tax_rate_list` param instead of `tax_rate`. - `tax_rate_list` object[] - `imposed_by` string, required — The entity applying the tax to this item. - `tax_rate` number, required — The tax rate applied to the item by the entity described in the `imposed_by` field. If the product is subject to only one tax rate, then use the single `tax_rate` param instead of `tax_rate_list`. - `taxes_charged` number — The portion of taxes charged for this item attributable to the `imposed_by` entity. - `taxes_exempted` number — The portion of taxes exempted for this item attributable to the `imposed_by` entity. - `taxes_charged` number — The amount of taxes charged for this item in USD. - `taxes_exempted` number — The amount of taxes exempted for this item in USD. - `tax_total` number — The total tax for this item in USD. - `eligibility` 'snap' | 'ebt_cash' | 'non_ebt' — The eligibility of the product. Must be `snap`, `ebt_cash`, or `non_ebt`. - `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` DeliveryAddressData — ⚠️ **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. - `city` string — The name of the city. - `country` string — Either `us` or `US`. Defaults to `US` if not provided. - `line1` string, required — The first line of the street address. - `line2` string, nullable — The second line of the street address. - `zipcode` string, required — The zip or postal code. - `state` string — The two-letter abbreviation, can be upper or lowercase, for the US state. - `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` string[] — 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_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 — **⚠️ 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 — 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. ## Response `200` __OK__ - Success - OrderResponse - `ref` string, required — A unique reference hash for the Forage `Order` object. - `snap_total` string, 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_total` string, 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_total` string, 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](https://docs.joinforage.app/reference/forage-sessions#fully-hosted-session) and is not included if the `Order` was created using a POST request to [`/capture_sessions/`](https://docs.joinforage.app/reference/create-capture-session)._ - `product_list` ProductDataResponse[] — A list of the products in the customer's cart. If there are no taxes applied to any of the products, then this field can be empty. _This value is only returned for [Fully Hosted Sessions](https://docs.joinforage.app/reference/forage-sessions#fully-hosted-session). It is not returned if the `Order` was created via a POST to [`/capture_sessions/`](https://docs.joinforage.app/reference/create-capture-session)._ - `id` integer, required — The unique identifier for the product. - `name` string, required — The name of the product. - `upc` string, nullable, required — The UPC of the product. - `gtin` string — The GTIN (Global Trade Item Number) of the product. - `unit_price` string, currency, required — The unit price of the product, represented as a numeric string. - `quantity` integer, required — The quantity of the product. - `tax_rate` string, decimal — The tax rate for the product, represented as a decimal string with at most six decimal places. A value of `0` indicates a tax rate of 0%, and a value of `1` indicates a tax rate of 100%. To set a 2% tax rate, for example, set the value to `0.02`. Use this field if the product is subject to only one tax rate. If multiple tax rates apply, for example both a state grocery tax and a sweetened beverage tax, then use the `tax_rate_list` param instead of `tax_rate`. - `tax_rate_list` object[] - `imposed_by` string, required — The entity applying the tax to this item. - `tax_rate` string, decimal, required — The tax rate applied to the item by the entity described in the `imposed_by` field, represented as a decimal string. If the product is subject to only one tax rate, then use the single `tax_rate` param instead of `tax_rate_list`. - `taxes_charged` string, currency, nullable — The portion of taxes charged for this item attributable to the `imposed_by` entity, represented as a numeric string. - `taxes_exempted` string, currency, nullable — The portion of taxes exempted for this item attributable to the `imposed_by` entity, represented as a numeric string. - `eligibility` 'snap' | 'ebt_cash' | 'non_ebt', nullable, required — The eligibility of the product. Must be `snap`, `ebt_cash`, or `non_ebt`. - `snap_amount` string, currency, nullable, required — The amount paid for this product using SNAP benefits in USD, represented as a numeric string. Precision is supported to the penny. - `cash_amount` string, currency, nullable, required — The amount paid for this product using EBT Cash benefits in USD, represented as a numeric string. Precision is supported to the penny. - `credit_debit_amount` string, currency, nullable, required — The amount paid for this product using credit or debit card in USD, represented as a numeric string. Precision is supported to the penny. - `tax_collected` string, currency, nullable, required — The tax amount collected for this product in USD, represented as a numeric string. Precision is supported to the penny. - `taxes_charged` string, currency, nullable, required — The amount of taxes charged for this product in USD, represented as a numeric string. Precision is supported to the penny. - `taxes_exempted` string, currency, nullable, required — The amount of taxes exempted for this product in USD, represented as a numeric string. Precision is supported to the penny. - `platform_fee` string, 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. - `delivery_address` DeliveryAddressData, required — ⚠️ **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. - `city` string — The name of the city. - `country` string — Either `us` or `US`. Defaults to `US` if not provided. - `line1` string, required — The first line of the street address. - `line2` string, nullable — The second line of the street address. - `zipcode` string, required — The zip or postal code. - `state` string — The two-letter abbreviation, can be upper or lowercase, for the US state. - `is_delivery` boolean, required — 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, 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_url` string, required — The URL to redirect your customer to if they cancel the order, passed in the original request to create a `Session`. - `supported_benefits` string[], 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_id` string, 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/`](https://docs.joinforage.app/reference/create-capture-session)._ **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, 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_id` string, 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_id` string, 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](https://docs.joinforage.app/reference/get-all-order-payments) to determine the cause of the error. - `payments` string[], required — An array of the unique reference hashes for any Forage `OrderPayment` objects associated with the `Order`. - `refunds` string[], required — An array of the unique reference hashes for any Forage `OrderRefund` objects associated with the `Order`. - `success_date` string, 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`. - `receipt` ReceiptData, required — 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`. This amount will be settled with the merchant after applying Forage's fees. - `ref_number` string — A unique reference hash for the Forage `Order`, `Payment`, or `Refund` associated with this receipt. Note: `receipt.ref_number` equals `ref`. - `is_voided` boolean — Whether the transaction associated with this receipt has been voided. If `false`, then the transaction finished processing as expected. If `true`, then the transaction was reversed. - `snap_amount` string — The USD amount charged/refunded to the SNAP balance of the EBT Card, represented as a numeric string. - `ebt_cash_amount` string, currency — The USD amount charged/refunded to the EBT Cash balance of the EBT Card, represented as a numeric string. - `cash_back_amount` string, currency, nullable — The USD amount of cash back given to the customer, represented as a numeric string. - `other_amount` string, currency — The USD amount charged/refunded to any payment method that is not an EBT Card, represented as a numeric string. - `sales_tax_applied` string, currency — The USD amount of taxes charged to the customer’s non-EBT payment instrument, represented as a numeric string. - `balance` BalanceResponse — An object that represents an EBT cardholder's account balance. - `id` integer — The unique identifier for the balance record. - `snap` string, currency — The available SNAP balance in USD on the customer’s EBT Card, represented as a numeric string. - `non_snap` string, currency — The available EBT Cash balance in USD on the customer's EBT Card, represented as a numeric string. - `updated` string, date-time — A UTC timestamp that indicates when the funds in the account last changed, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string. - `sequence_number` string — A transaction number for this `PaymentMethod`'s most recent balance check. Returned only for POS Terminal transactions; omitted from online merchant balance checks. - `last_4` string — The last four digits of the EBT Card number. - `message` string — A message from the EBT payment network that must be displayed to the EBT cardholder. - `transaction_type` 'Order' | 'Refund' | 'Payment' — A constant string that is used to identify the transaction type associated with the receipt. - `created` string, date-time — A UTC timestamp of when the Forage transaction object was created, represented as an [ISO 8601 date-time](https://www.iso.org/iso-8601-date-and-time-format.html) string. - `sequence_number` string, nullable — The terminal transaction sequence number for POS transactions. `null` for online (non-POS) transactions. - `expires_at` string, 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_shipping` boolean, nullable, required — Whether the order is to be shipped commercially. FNS uses this value in its database for statistics. - `previous_errors` object[], required — An array with information about the error. - `code` string — A short string that represents the error. - `message` string — A developer-facing message with more details about the error, not to be displayed to customers. - `source` object - `resource` string — The type of the Forage resource involved in the error. - `ref` string — If applicable, the ten character reference hash of the Forage resource that caused the error. An empty string if no specific individual resource was involved. - `details` object — Additional details about the error, if applicable. ## Other responses - `400` — __Bad request__ - The request was not accepted because of an error in the request body or path. - `401` — Unauthorized - `403` — Forbidden - `404` — __Not Found__ - The requested resource was not found. - `409` — Conflict - `429` — Too Many Requests - `500` — Internal Server Error --- [API](https://skmtc.net/joinforage/apis/forage-payments-api.md) · [All operations](https://skmtc.net/joinforage/apis/forage-payments-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/joinforage/forage-payments-api/versions/4b7212706fae/schema)