Order BI aggregation
POST /v2/order/analytics uses the same channel signature as other Open API v2 endpoints. It returns order aggregates without order details or personal data. Fetch individual orders on demand with /v2/order/search.
See the Order Analytics API Demo for an aggregate overview and daily trend UI. It uses synthetic data in the browser; live integrations should sign Open API requests on the partner backend.
Scope and limits
- The first version covers tpHotel orders in confirmed or completed status (internal statuses 4 and 5).
- Like the two-bound range in order search, filter.bookedAt filters order creation time with an inclusive start and exclusive end. Analytics requires both bounds. Use ISO 8601 timestamps with time zones. Day and month groups use UTC+08:00 boundaries. There is no time span limit.
- Day grouping on its own returns every matching date in the selected range and does not accept paging. Other groups, including combinations, support paging with up to 20 rows per page; hasMore indicates additional groups. Groups containing day or month are sorted by date and the other dimension in ascending order; other groups are sorted by total amount in descending order.
- groupBy accepts one group or an array of up to two distinct groups, such as
["channel", "day"]. Each row represents a combination with matching orders; empty combinations are omitted.nonecannot be combined with another group. - totalAmount and averageOrderAmount use the tax-inclusive CNY, USD, or JPY booking amount stored on orders, without conversion at today's exchange rate. averageOrderAmount is the average booking amount per order. orderCount, totalNights, and averageOrderNights are unitless; averageOrderNights is the average nights per order.
Request body
| Field | Required | Description |
|---|---|---|
| filter.bookedAt | Yes | [start time, end time], preferably ISO 8601 with a time zone; the end is exclusive. To include a full final day, use 00:00 on the following day |
| groupBy | No | One group or an array of up to two distinct groups: none (default), day, month, city, hotel, or channel; none cannot be combined with another group |
| preferred.currency | No | Currency for amount metrics: CNY (default), USD, or JPY; count and night metrics are unitless |
| preferred.language | No | Group name language: zh (default), en, or ja; ja currently falls back to English names |
| paging.skip / paging.limit | No | For all groups except standalone day; skip defaults to 0, limit defaults to 10 and has a maximum of 20 |
The endpoint rejects other filters such as city and hotel, as well as arbitrary Mongo criteria, advancedCriteria, channelRef, userRef, and sort. Unknown fields, invalid times, and excessive paging values produce an error.
Example
Send POST /v2/order/analytics with the headers described in Authentication and signing.
{
"preferred": { "currency": "CNY" },
"filter": { "bookedAt": ["2026-10-01T00:00:00+08:00", "2026-11-01T00:00:00+08:00"] },
"groupBy": "day"
}
Response shape (the number below is illustrative):
{
"currency": "CNY",
"groupBy": "day",
"period": { "from": "2026-10-01T00:00:00+08:00", "to": "2026-11-01T00:00:00+08:00" },
"rows": [{ "date": "2026-10-01", "totalAmount": { "amount": 1234.56, "currency": "CNY" }, "averageOrderAmount": { "amount": 617.28, "currency": "CNY" }, "orderCount": 2, "totalNights": 5, "averageOrderNights": 2.5 }],
"hasMore": false
}
To group by channel and date, send "groupBy": ["channel", "day"] with optional "paging": { "skip": 0, "limit": 20 }. Each response row then contains both channel and date, for example { "channel": { "_id": "...", "key": "partner", "name": "Partner" }, "date": "2026-10-01", ... }.
Each row contains the selected groups and all five measures: date (YYYY-MM-DD) for day, month (YYYY-MM) for month, city (with _id and name) for city, hotel (with _id and name) for hotel, and channel (with _id, key, and name) for channel. Combined groups put both group fields in each row, and the response preserves the groupBy array. Ungrouped rows have no group field. Amount metrics totalAmount and averageOrderAmount use amount and currency objects; orderCount, totalNights, and averageOrderNights are numbers. Days and combinations without matching orders are omitted; clients can fill missing dates with zero for charting. The response period reflects the requested filter.bookedAt range.
Errors
The endpoint uses the standard Open API error envelope with err.message. Missing filter.bookedAt, invalid time strings, an end time no later than the start, paging.limit over 20, paging on standalone day grouping, and unsupported fields such as metric, channelRef, or criteria are rejected before aggregation. Invalid signatures, inactive channels, and channels without API permission follow the existing Open API authentication rules.
{ "err": { "message": "paging.limit 必须为 1 至 20" } }