Analytics
Cross-shop sales, top products and shops, geography and revenue series.
/analytics/product-salesAggregates order line items whose text matches a keyword, or whose identity matches a saved product group, into a total plus a per-shop and per-listing breakdown. units is additive across all three levels and the three are guaranteed equal; orders is a distinct count per level and must NOT be summed. Matching runs on the line snapshot, so a renamed listing appears under each title it sold under, and a listing removed from the marketplace still reports its history. Revenue is gross of refunds.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
keyword | query | string | Words the listings share. All words must appear, each possibly in a different place; wrap in double quotes for an exact phrase. Case-insensitive and accent-insensitive. Minimum three characters, because the index is trigram-based and cannot serve a shorter pattern. min length 3 · max length 200 |
groupId | query | string | A saved product group. WINS over pattern ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ |
matchField | query | string | What One of: "TITLE", "SKU", "ANY" default "TITLE" |
from | query | string | Inclusive lower bound, a calendar day on the workspace timezone. pattern ^\d{4}-\d{2}-\d{2}$ |
to | query | string | Inclusive upper bound, a calendar day on the workspace timezone. pattern ^\d{4}-\d{2}-\d{2}$ |
channels | query | string | string[] | Restrict to one or more channels. |
shops | query | string | string[] | Restrict to one or more shops. |
Responses
| Status | Meaning (body: error envelope) |
|---|---|
| 400 | Validation failed, or the request is not valid for this resource. |
| 401 | The API key is missing, unknown, revoked or expired. |
| 403 | The API key lacks the required scope, or is not bound to this shop. |
| 404 | No such resource for this tenant. |
| 409 | The request conflicts with the current state (see |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/product-sales' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/analytics/top-productsRanked by revenue converted to USD BEFORE ranking, so a product sold across currencies ranks by its true blended value rather than by raw native magnitude. orders is a DISTINCT count and must not be summed across rows. trendPercent compares against the immediately preceding window of equal length and is 0 when no date range is given, because an unbounded window has no prior window - that is not "no change".
Parameters
| Name | In | Type | Description |
|---|---|---|---|
from | query | string | Start of the window, as a CALENDAR DAY ( |
to | query | string | End of the window, inclusive, same form as |
channels | query | string | string[] | Restrict to one or more channels. One of |
shops | query | string | string[] | Restrict to one or more shops, in either of the two forms |
seller | query | string | Restrict to orders attributed to one seller. |
limit | query | integer | How many rows to rank, up to 100. Omitted uses the server default, which differs per endpoint: 10 for min 1 · max 100 |
Responses
| Status | Meaning (body: error envelope) |
|---|---|
| 400 | Validation failed, or the request is not valid for this resource. |
| 401 | The API key is missing, unknown, revoked or expired. |
| 403 | The API key lacks the required scope, or is not bound to this shop. |
| 404 | No such resource for this tenant. |
| 409 | The request conflicts with the current state (see |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/top-products' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/analytics/top-shopsSame ranking rule as top-products, plus average order value per shop. A key bound to specific shops is answered for those shops only.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
from | query | string | Start of the window, as a CALENDAR DAY ( |
to | query | string | End of the window, inclusive, same form as |
channels | query | string | string[] | Restrict to one or more channels. One of |
shops | query | string | string[] | Restrict to one or more shops, in either of the two forms |
seller | query | string | Restrict to orders attributed to one seller. |
limit | query | integer | How many rows to rank, up to 100. Omitted uses the server default, which differs per endpoint: 10 for min 1 · max 100 |
Responses
| Status | Meaning (body: error envelope) |
|---|---|
| 400 | Validation failed, or the request is not valid for this resource. |
| 401 | The API key is missing, unknown, revoked or expired. |
| 403 | The API key lacks the required scope, or is not bound to this shop. |
| 404 | No such resource for this tenant. |
| 409 | The request conflicts with the current state (see |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/top-shops' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/analytics/geographyNo buyer personal data is involved: this is the country on the order, aggregated. sharePercent is computed WITHIN each row own currency, so in the native reporting mode the rows of each currency sum to 100 separately. A share across currencies would be a ratio of two different units.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
from | query | string | Start of the window, as a CALENDAR DAY ( |
to | query | string | End of the window, inclusive, same form as |
channels | query | string | string[] | Restrict to one or more channels. One of |
shops | query | string | string[] | Restrict to one or more shops, in either of the two forms |
seller | query | string | Restrict to orders attributed to one seller. |
Responses
| Status | Meaning (body: error envelope) |
|---|---|
| 400 | Validation failed, or the request is not valid for this resource. |
| 401 | The API key is missing, unknown, revoked or expired. |
| 403 | The API key lacks the required scope, or is not bound to this shop. |
| 404 | No such resource for this tenant. |
| 409 | The request conflicts with the current state (see |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/geography' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/analytics/channel-breakdownProfit is revenue minus tax, cost of goods, channel fees and marketplace shipping, corrected on a TikTok order without a refund to what TikTok’s settlement pays (see profit). READ profitCoverage BEFORE ACTING ON IT: a channel fee is only reconciled once a payout statement covering the order is pulled, and cost of goods is 0 for a product with no cost on record, so a recent window understates cost and overstates profit, while ordersMissingDiscountSplit counts TikTok orders whose profit reads LOW. ordersWithFee and ordersWithFeeEstimated OVERLAP and must never be added together - summed, they can exceed ordersTotal and read as broken.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
from | query | string | Start of the window, as a CALENDAR DAY ( |
to | query | string | End of the window, inclusive, same form as |
channels | query | string | string[] | Restrict to one or more channels. One of |
shops | query | string | string[] | Restrict to one or more shops, in either of the two forms |
seller | query | string | Restrict to orders attributed to one seller. |
Responses
| Status | Meaning (body: error envelope) |
|---|---|
| 400 | Validation failed, or the request is not valid for this resource. |
| 401 | The API key is missing, unknown, revoked or expired. |
| 403 | The API key lacks the required scope, or is not bound to this shop. |
| 404 | No such resource for this tenant. |
| 409 | The request conflicts with the current state (see |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/channel-breakdown' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/analytics/seller-performanceTakes ONLY a date range: there is no channel, shop or seller filter. A SHOP-BOUND KEY IS REFUSED with 403 shop_not_permitted - this report aggregates every shop in the workspace and cannot be narrowed, so answering a bound key would hand it money earned on shops it was not issued for. Use an unbound key, or /analytics/top-shops, which does honour the binding. The seller display NAME and EMAIL are deliberately not published: you hold sellerId, there is no roster endpoint to join it against, and the email is a DoctorX user’s personal data that no scope here gates. revenue - cost + settlementAdjustment = profit on every row: cost is everything the profit deducts (tax, cost of goods, channel fees, marketplace shipping), and settlementAdjustment is what TikTok’s settlement pays that those deductions cannot express. The cost of goods inside cost is USD in both reporting modes because it is seller-set and has no currency column, so on a non-USD row in the native mode cost and profit mix units.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
from | query | string | Start of the window, as a CALENDAR DAY ( |
to | query | string | End of the window, inclusive, same form as |
Responses
| Status | Meaning (body: error envelope) |
|---|---|
| 400 | Validation failed, or the request is not valid for this resource. |
| 401 | The API key is missing, unknown, revoked or expired. |
| 403 | The API key lacks the required scope, or is not bound to this shop. |
| 404 | No such resource for this tenant. |
| 409 | The request conflicts with the current state (see |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/seller-performance' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/analytics/revenue-seriesOMITTING granularity DOES NOT MEAN "day": the bucket size is chosen from the length of the range, so a one-day window returns 24 hourly points instead of a single bar. series and totals are the single blended view and are NULL in the native reporting mode, where points from different currencies cannot share one value axis; byCurrency is always populated in both modes and carries exactly one entry (USD) in the authoritative mode, so reading it alone works without branching on the mode. byCurrency is ordered by ORDER COUNT descending, deliberately: ranking it by revenue would float a high-denomination currency to the top and call it the main one.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
from | query | string | Start of the window, as a CALENDAR DAY ( |
to | query | string | End of the window, inclusive, same form as |
channels | query | string | string[] | Restrict to one or more channels. One of |
shops | query | string | string[] | Restrict to one or more shops, in either of the two forms |
seller | query | string | Restrict to orders attributed to one seller. |
granularity | query | string | Bucket size. OMITTED IS NOT "day": the server chooses from the length of the range, so a one-day window returns 24 hourly points instead of a single bar. One of: "hour", "day", "week", "month" |
Responses
| Status | Meaning (body: error envelope) |
|---|---|
| 400 | Validation failed, or the request is not valid for this resource. |
| 401 | The API key is missing, unknown, revoked or expired. |
| 403 | The API key lacks the required scope, or is not bound to this shop. |
| 404 | No such resource for this tenant. |
| 409 | The request conflicts with the current state (see |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/revenue-series' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/analytics/busiest-daysAll 31 days are returned, zero-order days included, so a chart axis is stable. revenue is null in the native reporting mode: a single cross-currency total cannot be honest, and this pivot ranks by ORDER COUNT, so nothing that matters here is lost.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
from | query | string | Start of the window, as a CALENDAR DAY ( |
to | query | string | End of the window, inclusive, same form as |
channels | query | string | string[] | Restrict to one or more channels. One of |
shops | query | string | string[] | Restrict to one or more shops, in either of the two forms |
seller | query | string | Restrict to orders attributed to one seller. |
Responses
| Status | Meaning (body: error envelope) |
|---|---|
| 400 | Validation failed, or the request is not valid for this resource. |
| 401 | The API key is missing, unknown, revoked or expired. |
| 403 | The API key lacks the required scope, or is not bound to this shop. |
| 404 | No such resource for this tenant. |
| 409 | The request conflicts with the current state (see |
| 422 | The marketplace rejected the request; |
| 429 | Back off and retry. |
| 500 | A defect on our side ( |
Request sample
curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/busiest-days' \
-H "Authorization: Bearer $DOCTORX_API_KEY"