v1

latestOpenAPI 3.0.02026-07-244352379.2 KB

Reports

Retrieve an Order Report

📘 Fully Hosted And Custom Integrations Only

Order Reports are only relevant to Fully Hosted and Custom integrations. Only Fully Hosted and Custom integrations generate Forage Orders. Use any of the other /reporting/ endpoints if you’re building with an SDK.

A GET request to /reporting/orders/ retrieves an Order Report.

On success, the API returns a list of Forage Orders created during the provided reporting period.

get/reporting/orders/

Query parameters

start_datestring date required

The date that the reporting period starts, represented as an ISO 8601 UTC date string, inclusive. The result set includes all reported items that occurred on the date.

end_datestring date required

The date that the reporting period ends, represented as an ISO 8601 UTC date string, inclusive. The result set includes all reported items that occurred on the date.

limitinteger

The maximum number of objects to include in the results array. Not to exceed 1000. If the limit exceeds 1000, then Forage returns a 400 error response.

Defaults to 100.

cursorstring

The starting point for the results, as returned in a previous /reporting/ request. Find a cursor in the URL returned in the next and/or previous response values.

statusstring

The status of the Orders to be returned in the response. succeeded is the only currently supported value, instructing the start_date and end_date params to refer to the order’s success_date, rather than its created value. The status filter has no effect if any other value is applied or if excluded from the request.

Headers

Merchant-Accountstring

A unique merchant ID that Forage provides during onboarding, as in 123ab45c67. The Merchant ID can be found in the Forage sandbox or production dashboard.

If querying on behalf of a platform that supports multiple merchants, then omitting this header returns platform-wide results. You must indicate a Merchant-Account header to retrieve results for a specific merchant on a platform.

API-Versionstring

The Forage version, represented as a string with the format of a YYYY-MM-DD date.

If not specified in the request header, then the version defaults to the value set in the Forage dashboard.

Response

OK - Success

nextstring nullable

A URL that you can send a GET to in order to retrieve the next set of results. Alternatively, you can retrieve the cursor value from the URL and pass it in the body of a new request.

This value is null if there are no more results.

previousstring nullable

A URL that you can send a GET to in order to retrieve the previous set of results. Alternatively, you can retrieve the cursor value from the URL and pass it in the body of a new request.

This value is null if the response includes the first set of results.

Example response

{
  "next": "https://api.sandbox.joinforage.app/reporting/orders/?cursor=cD0yMDIzLTAxLTMxKzIxJTNBMzElM0ExNC40NTUxNjMlMkIwMCUzQTAw&end_date=2021-02-28&start_date=2021-01-31",
  "results": [
    {
      "ref": "b085e45a54",
      "status": "draft",
      "snap_eligible_total": "25.99",
      "ebt_cash_eligible_total": "21.23",
      "remaining_total": "44.39",
      "sales_tax_applied": "5.12",
      "snap_paid": "86.29",
      "ebt_cash_paid": "15.22",
      "credit_debit_paid": "67.90",
      "merchant_fns_number": "1234567",
      "created": "2021-06-15T00:11:50.000000Z",
      "success_date": "2021-06-16T00:11:50.000000Z",
      "payments": [
        "cd62e45f33",
        "a2f4e45665"
      ],
      "refunds": [
        "aaabe45432",
        "7e84e45db7"
      ],
      "external_location_id": "6e3b2ff7-51c8-4c64-befa-2eac90f7c3e9"
    }
  ]
}