API Income Report

Income Report API

Create an API key with the report.income scope first, following Enable API.

Overview

The Income Report API returns the rows of your Income report for a date range as JSON, so you can load your income into your own reporting tools, spreadsheets or accounting systems. It returns the same lines, columns and totals as the Income report on screen, for every location and staff member.

Only staff whose role has the Financial Reports permission can create a key with the report.income scope.

Base URL

https://examplebusiness.com/Api/v1/Reports/Income

Replace examplebusiness.com with your own BookingTimes website address.

Endpoint

HTTP Method: GET
Endpoint: /Api/v1/Reports/Income

Authentication

Send your API key in the x-api-key header.

Query Parameters

All parameters are optional and passed in the query string.

Parameter	Type	Description
`DateFrom`	Date (yyyy-MM-dd)	The first day of the range. Defaults to yesterday.
`DateTo`	Date (yyyy-MM-dd)	The last day of the range, inclusive. Defaults to `DateFrom`. The range can be up to 31 days.
`DateType`	String	`P` to select by paid date (the default) or `B` by booking date.
`LocationId`	Integer	Only this location. Leave out for every location.
`StaffId`	Integer	Only this staff member. Leave out for all staff.
`SaleType`	String	Only one type of transaction: `I` income only, `B` bookings, `P` product sales, `S` sales, `W` web sales, `R` refunds or `E` expenses. Leave out for everything.
`ShowClientCredits`	Boolean	`true` (the default) includes the voucher, client account and organisation account payment columns (Account CR); `false` leaves them out, like the report's Show Client Credits option.

Example Request

Income paid from 1 to 13 October 2026:

curl -H "x-api-key: {your_api_key}" "https://examplebusiness.com/Api/v1/Reports/Income?DateFrom=2026-10-01&DateTo=2026-10-13"

The same request in PowerShell:

$income = Invoke-RestMethod -Uri "https://examplebusiness.com/Api/v1/Reports/Income?DateFrom=2026-10-01&DateTo=2026-10-13" -Headers @{ "x-api-key" = "{your_api_key}" }
$income.Rows | Export-Csv income.csv -NoTypeInformation

Response

A successful request returns 200 OK and a JSON object:

Field	Description
`DateFrom`, `DateTo`, `DateType`, `ShowClientCredits`	The values the report was run with.
`Columns`	Each column in the report's order: its `Name` (the field name in each row), the `Heading` shown on the report, and the `Group` heading above it (Income, Account DR, Transaction Detail or Account CR). A column with no heading, such as `InvoiceUrl`, supports another column on the report.
`RowCount`	The number of rows returned.
`Rows`	One object per report line, keyed by column name. Each row includes the report's totals: `TotalIncome`, `TotalAccountDr`, `Total` and, when client credits are shown, `TotalAccountCr`.

The columns follow your business settings, just as the report does. For example, the GST or VAT column only appears when your business charges it, and the payout columns only appear when your online payments are paid out through Stripe Connect (see Receiving online payouts). Read Columns rather than assuming a fixed list.

Example response (shortened):

{
  "DateFrom": "2026-10-01",
  "DateTo": "2026-10-13",
  "DateType": "P",
  "ShowClientCredits": true,
  "Columns": [
    { "Name": "SaleDate", "Heading": "Paid Date", "Group": null },
    { "Name": "SaleTypeDescr", "Heading": "Type", "Group": null },
    { "Name": "InvoiceNbr", "Heading": "Invoice", "Group": null },
    { "Name": "ClientName", "Heading": "Client", "Group": null },
    { "Name": "ServiceName", "Heading": "Item", "Group": null },
    { "Name": "BusOnlineAmt", "Heading": "Online", "Group": "Income" },
    { "Name": "TotalIncome", "Heading": "Total Income", "Group": null },
    { "Name": "Total", "Heading": "Total", "Group": "Transaction Detail" }
  ],
  "RowCount": 1,
  "Rows": [
    {
      "SaleDate": "2026-10-02T00:00:00",
      "SaleTypeDescr": "Booking",
      "InvoiceNbr": 10452,
      "ClientName": "Jane Citizen",
      "ServiceName": "60 Minute Driving Lesson",
      "BusOnlineAmt": 85.00,
      "TotalIncome": 85.00,
      "Total": 85.00
    }
  ]
}

Error Responses

Errors return a status code and a JSON body such as {"result":"DateFrom must be a date as yyyy-MM-dd"}.

Status Code	Description
`400 Bad Request`	The `x-api-key` header is missing, or a parameter is invalid. The `result` says which parameter and what it must be.
`401 Unauthorized`	The API key is wrong or has been revoked.
`403 Forbidden`	The API key does not have the `report.income` scope.
`405 Method Not Allowed`	Only `GET` is accepted.
`429 Too Many Requests`	The rate limit has been reached. Wait and try again.
`406 Not Acceptable`	The report could not be produced. Try again, and contact support if it continues.

Rate Limits

The Income Report API allows 4 requests per minute and 60 per day. That suits a scheduled daily or hourly download; for a longer period, request it one month at a time.

Notes

Replace examplebusiness.com with your BookingTimes website address and {your_api_key} with the key from Enable API.
The response includes client names and payment details, so store the key and the downloaded data securely.
Dates are in your business's own time zone.

Contact and Support

For additional assistance or to report issues with the API, please contact support@bookingtimes.com or visit our Support Page.