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

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" } }