An Order
object is the outcome of a Forage Session.
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
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, thestatus
value is alwaysdraft
, and thereceipt
value is alwaysnull
. 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 theexpires_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
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
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
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
receipt
The
receipt
value is null when theOrder
is first created and until receipt data is available. Pass theref
returned in the response that created the order's parentSession
in periodic GET requests to/orders/{order_ref}/
until thestatus
of theOrder
issucceeded
. 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
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
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'
Update an Order
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,
}
'