Orders

✅
Order objects are only relevant to Fully Hosted and Custom integrations.
If you’re building with a Forage SDK, then use the Payments endpoints.

Every request to create a Forage Session also generates a corresponding Order, an object that represents the customer’s interaction with the Forage Checkout UI.

While you create an Order via the Sessions endpoints, with the Orders endpoints you can:

Retrieve an Order: GET /orders/{order_ref}/
Update an Order: POST /orders/{order_ref}/

The order_ref path param is the ref value that is returned in the response object of the request that created the original Forage Session.

`Order` object

{
  "ref": "e0f7607d5f",
  "snap_total": "10.00",
  "ebt_cash_total": "9.00",
  "remaining_total": "0.00",
  "product_list": [],
  "status": "draft",
  "delivery_address": {
    "city": "San Francisco",
    "country": "US",
    "line1": "1856 Market St.",
    "line2": "Apt. 3",
    "state": "CA",
    "zipcode": "94105,"
  },
  "is_delivery": false,
  "success_redirect_url": "",
  "cancel_redirect_url": "",
  "supported_benefits": [
    "snap",
    "ebt_cash",
    "non_ebt"
  ],
  "success_date": null,
  "receipt": null,
  "customer_id": null,
  "is_commercial_shipping": null,
  "expires_at": "2023-09-29T18:33:28.315051Z",
  "psp_customer_id": null,
  "external_order_id": null,
  "payments": [],
  "refunds": []
}

✅
When an Order is first created, the status value is always draft, and the receipt value is always null. Send periodic GET requests to /orders/{order_ref}/ to retrieve updated data.

🚧
If an Order is not captured or canceled within 30 minutes of when it is created, then it expires. Inspect the expires_at field to find a timestamp of the expiration.

Properties

Property	Type	Description
`ref`	string	A unique reference hash for the Forage `Order` object.
`snap_total`	string	The SNAP eligible portion of the order cost in USD. Precision to the penny is supported.
`ebt_cash_total`	string	The EBT Cash eligible portion of the order cost in USD. Precision to the penny is supported.
`remaining_total`* *Not included if the Order was created via a POST to `/capture_sessions/`	string	The portion of the order total in USD that is not SNAP or EBT Cash eligible. This amount must be charged to a credit or debit card. Precision to the penny is supported.
`product_list`* *Not included if the Order was created via a POST to `/capture_sessions/`	array of objects	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. Refer to `product_list` for details.
`status`	string	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`
`delivery_address`	object	The address for delivery or pickup of the order. Refer to `delivery_address` for details.
`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, passed in the original request to create a `Session`.
`cancel_redirect_url`	string	The URL to redirect your customer to if they cancel the order, passed in the original request to create a `Session`.
`supported_benefits`	array of strings	The set of benefits that can be applied at checkout, including any or all of the values in: `["snap", "ebt_cash", "non_ebt"]`
`success_date`	ISO 8601 date-time string	The date when the `Order` was successfully charged to the associated `PaymentMethod`. This value is `null` if the `status` of the `Order` is not yet `succeeded`.
`receipt`	object	The information that you’re required to display to the customer after the `Order` status is `succeeded`, according to FNS regulations. This field is `null` if receipt data is not yet available for the `Order`. Refer to `receipt` for details.
`customer_id`	string	A unique ID for the end customer making the payment.
`is_commercial_shipping`	boolean	Whether the order is to be shipped commercially. FNS uses this value in its database for statistics.
`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.
`expires_at`	ISO 8601 date-time string	A timestamp of when the `Order` will expire if it is not captured or canceled, set to 30 minutes from when the `Order` is created.
`psp_customer_id`* *The value of this field is `null` if the Order was created via a POST to `/capture_sessions/`	string	The third-party credit/debit payment processor’s unique identifier for the customer.
`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.
`payments`	array of strings	An array of the unique reference hashes for any Forage `OrderPayment` objects associated with the Order.
`refunds`	array of strings	An array of the unique reference hashes for any Forage `OrderRefunds` associated with the `Order`.

`product_list`

Every object in a product_list that represents an item in a customer’s cart includes the following fields:

Property	Type	Description
`name`	string	The name of the item.
`upc`	string	The item’s Universal Product Code.
`unit_price`	string	The cost of a single item.
`quantity`	number	The number of the items in the customer’s cart.
`tax_rate`	number	The tax rate for the item, 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`.
`taxes_charged`	number	The taxes charged to the customer in USD. Precision to the penny is supported.
`taxes_exempted`	number	The total amount of taxes that the order is exempt from. Precision to the penny is supported.
`eligibility`	string	The EBT benefits, if any, that can be used to pay for the item. One of: - `ebt_cash` - `non_ebt` - `snap`

`tax_rate_list`

If multiple tax rates apply to an item in a product_list, then in the product_list instead of tax_rate pass tax_rate_list, including the following fields:

Property	Type	Description
`imposed_by`	string	The name of the entity applying the tax.
`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%. If only one tax rate applies, then use the single `tax_rate` param instead.

`delivery_address`

Property	Type	Description
`city`	string	The name of the city.
`country`	string	The constant string `US`.
`line1`	string	The first line of the street address.
`line2`	string	The second line of the street address.
`state`	string	A two-letter abbreviation for the US state.
`zipcode`	string	A zip or postal code.

`receipt`

🚧
The receipt value is null when the Order is first created and until receipt data is available. Pass the ref returned in the response that created the order's parent Session in periodic GET requests to /orders/{order_ref}/ until the status of the Order is succeeded. At that point, the receipt data, including the balance, is up-to-date.

Property	Type	Description
`ref_number`	string	The reference hash of the `Order`.
`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 amount charged/refunded to the SNAP balance of the EBT Card, represented as a numeric string.
`ebt_cash_amount`	string	The amount charged/refunded to the EBT Cash balance of the EBT Card, represented as a numeric string.
`other_amount`	string	The amount charged or refunded to any payment method that is not an EBT Card, represented as a numeric string.
`sales_tax_applied`	string	The USD amount of taxes charged to the customer’s non-EBT payment instrument, represented as a numeric string.
`balance`	object	Refer to `balance` for details.
`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`	string	A constant string that is used to identify the transaction associated with the receipt. Always `Order` for orders.
`created`	ISO-8601 date-time string	A timestamp of when the `Order` was created.

`balance`

Property	Type	Description
`snap`	string	The available SNAP balance on the customer’s EBT Card, represented as a numeric string.
`non_snap`	string	The available EBT Cash balance on the EBT Card, represented as a numeric string.
`updated`	ISO-8601 date-time string	The date-time when the funds in the account last changed.

Example requests

Retrieve an `Order`

curl --request GET \
     --url https://api.sandbox.joinforage.app/api/orders/{order_ref}/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Merchant-Account: 9000055' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'

📘
GET /orders/{order_ref}/ documentation

Update an `Order`

curl --request POST \
     --url https://api.sandbox.joinforage.app/api/orders/{order_ref}/ \
     --header 'Authorization: Bearer <authentication-token>' \
     --header 'Merchant-Account: 9000055' \
     --header 'accept: application/json' \
     --header 'content-type: application/json'\
     --data '
{
  "is_delivery": true,
}
'

📘
POST /orders/{order_ref}/ documentation

Order object

Properties

product_list

tax_rate_list

delivery_address

receipt

balance

Example requests

Retrieve an Order

Update an Order

`Order` object

`product_list`

`tax_rate_list`

`delivery_address`

`receipt`

`balance`

Retrieve an `Order`

Update an `Order`