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": "abc123",
"is_commercial_shipping": null,
"expires_at": "2023-09-29T18:33:28.315051Z",
"psp_customer_id": null,
"external_order_id": null,
"payments": [],
"refunds": [],
"previous_errors": []
}
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 | A UTC-8 timestamp of 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. 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.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 for the same customer, then the customer_id should be the same in both requests. |
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 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. |
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 . |
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. |
previous_errors | array | An array of objects that detail information about any errors triggered by the request. If the request was successful and without errors, then the field is returned as an empty array. Refer to previous_errors for details. |
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 UTC-8 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 | A UTC-8 date-time timestamp of when the funds in the account last changed. |
previous_errors
previous_errors
Each object in the previous_errors
array includes the following fields:
Property | Type | Description |
---|---|---|
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 | An object that details the specific source of the Forage error, including two keys: - resource : The type of the Forage resource involved in the error.- ref : 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. |
Order
lifecycle
Order
lifecycleA Forage Order
enters different lifecycle stages depending on a customer’s checkout interactions. You can track an Order
's stage in the lifecycle via its status
attribute.
🔄 draft
An Order
has been created and is pending further action. It has not yet been submitted for processing, so you can continue to add OrderPayments
to the Order
or to modify payment totals.
From a UX perspective, Forage creates an Order
when a customer completes an action, like clicking "Place Order", that launches the Forage Checkout UI.
From draft
, an Order
moves to either processing
or canceled
.
🔄 processing
An attempt is made to process payment and capture the Order
.
You can no longer add OrderPayments
or modify payment totals.
From a UX perspective, an Order
moves to the processing
state when a customer submits their PIN to authorize payment in the Forage Checkout UI.
Forage is waiting on a response from the upstream EBT benefits networks.
From processing
, an Order
can move to either succeeded
or failed
.
✅ succeeded
The Order
has been successfully captured.
The merchant can expect to receive the funds.
The customer can expect the payment amount to be debited from their account balance.
succeeded
is a terminal state. You can no longer modify the Order
or resubmit it for capture. The Order
lifecycle is complete.
❌ failed
The Order
capture failed.
It is possible that some OrderPayments
succeeded, but it is guaranteed that at least one failed.
You can still add new OrderPayments
to the Order
or modify totals.
Forage automatically moves the Order
to the canceled
stage after 30 minutes.
✖️ canceled
The Order
has expired. It cannot be modified or resubmitted for capture. If there were any successful OrderPayments
for the Order
, then Forage automatically refunded them.
An Order
can only be canceled if it is at the draft
or failed
state.
If a customer clicks the "Cancel and return to the checkout page" prompt in the Forage UI, then only the OrderPayment
associated with the Order
is canceled.
Forage automatically cancels an Order
after 30 minutes of inactivity.
canceled
is a terminal state. The Order
lifecycle is complete.
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,
}
'