---
title: "Get yield insights"
method: GET
path: "/shop/yield-insights"
tags: ["YieldInsights"]
---

# Get yield insights

`GET /shop/yield-insights`

Returns a site-level summary of how yield pricing is set up and
performing over a recent reporting period: the opportunity for
demand-based pricing (utilisation, peak and quiet spells) and what
yield rules have earned since they were switched on.

The four state flags (`has_occupancy_data`, `is_yield_enabled`,
`opportunities.has_data`, `performance.has_data`) are always
present, so a dashboard can decide which panels to render before
reading any stats. The stat fields themselves are `null` until the
underlying calculation has data to work from.

Monetary amounts are integers in the minor units of the top-level
`currency` — format them client-side.

For a per-sale breakdown of every price a yield rule moved, use the
[yielded sales report](/endpoints/Reports#listYieldedSales).

## Query parameters

- `site_id` string, uuid, required
- `period` 'last_30_days' | 'last_60_days' | 'last_90_days'

## Response `200`

The yield insights were successfully retrieved.

- object
  - `data` YieldInsights, required — A site-level summary of how yield pricing is set up and performing over a recent reporting period. The state flags (`has_occupancy_data`, `is_yield_enabled`, `opportunities.has_data`, `performance.has_data`) are always present; the stat fields inside `opportunities` and `performance` are `null` until the underlying calculation has data to work from.
    - `period` 'last_30_days' | 'last_60_days' | 'last_90_days', required — The reporting period the insights were calculated over.
    - `window` YieldInsightsWindow, nullable, required — The concrete datetime window the requested `period` resolved to, or `null` when the site has no occupancy history at all to build a window from. When the site's data starts too recently to cover the whole requested period, `starts_at` reflects where the data actually begins rather than the full period.
      - `starts_at` string, date-time, required — When the reporting window starts.
      - `ends_at` string, date-time, required — When the reporting window ends.
    - `currency` string, required — The ISO-4217 currency code every monetary amount in this response (`performance.additional_revenue`, `performance.aov_uplift_amount`) is denominated in. The amounts themselves are integers in this currency's minor units.
    - `has_occupancy_data` boolean, required — Whether the site has any occupancy data at all. When `false` there is nothing to calculate insights from, so the stat fields elsewhere in the response are `null`.
    - `is_yield_enabled` boolean, required — Whether yield pricing is switched on for the site. When `false` the `performance` stats have nothing to measure and are `null`.
    - `opportunities` YieldInsightsOpportunities, required — Where the opportunity for demand-based pricing lies — how busy the site runs on average, and how many peak and quiet spells its occupancy shows over the reporting window.
      - `has_data` boolean, required — Whether there is enough occupancy data to calculate the opportunity stats. When `false` every stat field in this object is `null`; the two threshold fields are always present.
      - `avg_utilisation_percent` integer, nullable, required — The site's average utilisation across the reporting window, as a whole-number percentage.
      - `bookable_area_count` integer, nullable, required — The number of bookable areas the utilisation is measured across.
      - `peak_period_count` integer, nullable, required — The number of periods in the reporting window where utilisation reached `peak_threshold_percent` or above.
      - `quiet_period_count` integer, nullable, required — The number of periods in the reporting window where utilisation fell to `quiet_threshold_percent` or below.
      - `peak_threshold_percent` integer, required — The utilisation percentage at or above which a period counts as a peak.
      - `quiet_threshold_percent` integer, required — The utilisation percentage at or below which a period counts as quiet.
    - `performance` YieldInsightsPerformance, required — What yield pricing has earned for the site since it was switched on. Monetary amounts are integers in the minor units of the top-level `currency` — format them client-side.
      - `has_data` boolean, required — Whether there is enough yield activity to calculate the performance stats. When `false` every other field in this object is `null`.
      - `additional_revenue` integer, nullable, required — The extra revenue attributed to yield price adjustments since `additional_revenue_since`, as an integer in the minor units of the top-level `currency` (e.g. `648000` is £6,480.00 when the currency is `GBP`) — not a pre-formatted display string.
      - `additional_revenue_since` string, date, nullable, required — The date `additional_revenue` accumulates from — when yield pricing was switched on for the site.
      - `aov_uplift_amount` integer, nullable, required — How much yield pricing has lifted the site's average order value — the uplift itself, not the average order value. An integer in the minor units of the top-level `currency` (e.g. `1420` is £14.20 when the currency is `GBP`), not a pre-formatted display string.
      - `aov_uplift_percent` integer, nullable, required — The average order value uplift as a whole-number percentage of the pre-yield average.
      - `bookings_at_high_peak_percent` integer, nullable, required — The share of bookings taken during high-peak periods, as a whole-number percentage.
      - `bookings_by_tier` YieldInsightsBookingsByTierEntry[], nullable, required — The share of bookings and revenue per reporting tier over the window. `null` when `has_data` is `false`.
        - `tier` 'standard' | 'low' | 'high' | 'peak', required
        - `count` integer, required — The number of bookings in this tier over the reporting window.
        - `share_percent` integer, required — This tier's share of all bookings in the window, as a whole-number percentage. Sums to 100 across all tiers.
        - `revenue` integer, required — Total revenue from this tier's bookings, as an integer in the minor units of the top-level `currency`.

## Other responses

- `401` — The user is unauthenticated
- `403` — The authenticated user does not have permission.
- `422` — The request didn't pass validation

---

[API](https://skmtc.dev/try/apis/trybe-api.md) · [All operations](https://skmtc.dev/try/apis/trybe-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/try/trybe-api/revisions/f37f92702da5/schema)