Orders

📘

Order Use By Integration Type

Order objects are only used in Fully Hosted and Custom integrations. SDK-based integrations should 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": "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": []
}

📘

Initial Order Status And Receipt

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.

⚠️

Order Expiration Timing

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

product_list

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

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:

delivery_address

receipt

⚠️

receipt Unavailable Until Order Succeeds

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.

balance

previous_errors

Each object in the previous_errors array includes the following fields:

Order lifecycle

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

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.

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' 

For more information, see 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,
}
' 

For more information, see POST /orders/{order_ref}/ documentation.