---
title: "API Income Report"
slug: "api-income-report"
updated: 2026-10-14T21:46:07Z
published: 2026-10-14T21:46:07Z
canonical: "support.bookingtimes.com/api-income-report"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.bookingtimes.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Income Report

## Income Report API

Create an API key with the `report.income` scope first, following [Enable API](/v2/docs/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

```plaintext
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:

```bash
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:

```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](/v2/docs/payouts)). Read `Columns` rather than assuming a fixed list.

Example response (shortened):

```json
{
  "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](/v2/docs/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](https://support.bookingtimes.com/).