DoctorX logoDoctorX Get an API key

Analytics

Cross-shop sales, top products and shops, geography and revenue series.

Aggregates 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

NameInTypeDescription
keyword
querystring

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
querystring

A saved product group. WINS over keyword: a group's rules are its definition, so a keyword is not allowed to narrow them further.

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
querystring

What keyword is matched against. TITLE is the default because it is the only field populated on every order line. ANY also matches SKU, variant and both channel ids, which is faster but cannot tell the fields apart. Ignored when groupId is set.

One of: "TITLE", "SKU", "ANY"

default "TITLE"

from
querystring

Inclusive lower bound, a calendar day on the workspace timezone.

pattern ^\d{4}-\d{2}-\d{2}$

to
querystring

Inclusive upper bound, a calendar day on the workspace timezone.

pattern ^\d{4}-\d{2}-\d{2}$

channels
querystring | string[]

Restrict to one or more channels.

shops
querystring | string[]

Restrict to one or more shops.

Responses

200ProductSalesResponse
StatusMeaning (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 error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/product-sales' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/analytics/top-products

Ranked 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

NameInTypeDescription
from
querystring

Start of the window, as a CALENDAR DAY (YYYY-MM-DD) in the workspace timezone, not an instant. Omit both bounds for all time.

to
querystring

End of the window, inclusive, same form as from.

channels
querystring | string[]

Restrict to one or more channels. One of tiktok, ebay, etsy, amazon. Repeat the parameter (?channels=tiktok&channels=ebay) or comma-join it (?channels=tiktok,ebay); both are accepted, and an unrecognised key is refused BY NAME rather than dropped.

shops
querystring | string[]

Restrict to one or more shops, in either of the two forms channels accepts. A key bound to specific shops is additionally constrained to its own binding, so naming a shop it was not issued for narrows the result rather than widening it.

seller
querystring

Restrict to orders attributed to one seller.

limit
queryinteger

How many rows to rank, up to 100. Omitted uses the server default, which differs per endpoint: 10 for top-products, 12 for top-shops.

min 1 · max 100

Responses

200TopProductsResponse
StatusMeaning (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 error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/top-products' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/analytics/top-shops

Same ranking rule as top-products, plus average order value per shop. A key bound to specific shops is answered for those shops only.

Parameters

NameInTypeDescription
from
querystring

Start of the window, as a CALENDAR DAY (YYYY-MM-DD) in the workspace timezone, not an instant. Omit both bounds for all time.

to
querystring

End of the window, inclusive, same form as from.

channels
querystring | string[]

Restrict to one or more channels. One of tiktok, ebay, etsy, amazon. Repeat the parameter (?channels=tiktok&channels=ebay) or comma-join it (?channels=tiktok,ebay); both are accepted, and an unrecognised key is refused BY NAME rather than dropped.

shops
querystring | string[]

Restrict to one or more shops, in either of the two forms channels accepts. A key bound to specific shops is additionally constrained to its own binding, so naming a shop it was not issued for narrows the result rather than widening it.

seller
querystring

Restrict to orders attributed to one seller.

limit
queryinteger

How many rows to rank, up to 100. Omitted uses the server default, which differs per endpoint: 10 for top-products, 12 for top-shops.

min 1 · max 100

Responses

200TopShopsResponse
StatusMeaning (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 error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/top-shops' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

No 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

NameInTypeDescription
from
querystring

Start of the window, as a CALENDAR DAY (YYYY-MM-DD) in the workspace timezone, not an instant. Omit both bounds for all time.

to
querystring

End of the window, inclusive, same form as from.

channels
querystring | string[]

Restrict to one or more channels. One of tiktok, ebay, etsy, amazon. Repeat the parameter (?channels=tiktok&channels=ebay) or comma-join it (?channels=tiktok,ebay); both are accepted, and an unrecognised key is refused BY NAME rather than dropped.

shops
querystring | string[]

Restrict to one or more shops, in either of the two forms channels accepts. A key bound to specific shops is additionally constrained to its own binding, so naming a shop it was not issued for narrows the result rather than widening it.

seller
querystring

Restrict to orders attributed to one seller.

Responses

200GeoDistributionResponse
StatusMeaning (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 error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/geography' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/analytics/channel-breakdown

Profit 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

NameInTypeDescription
from
querystring

Start of the window, as a CALENDAR DAY (YYYY-MM-DD) in the workspace timezone, not an instant. Omit both bounds for all time.

to
querystring

End of the window, inclusive, same form as from.

channels
querystring | string[]

Restrict to one or more channels. One of tiktok, ebay, etsy, amazon. Repeat the parameter (?channels=tiktok&channels=ebay) or comma-join it (?channels=tiktok,ebay); both are accepted, and an unrecognised key is refused BY NAME rather than dropped.

shops
querystring | string[]

Restrict to one or more shops, in either of the two forms channels accepts. A key bound to specific shops is additionally constrained to its own binding, so naming a shop it was not issued for narrows the result rather than widening it.

seller
querystring

Restrict to orders attributed to one seller.

Responses

200ChannelBreakdownResponse
StatusMeaning (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 error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/channel-breakdown' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Takes 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

NameInTypeDescription
from
querystring

Start of the window, as a CALENDAR DAY (YYYY-MM-DD) in the workspace timezone, not an instant. Omit both bounds for all time.

to
querystring

End of the window, inclusive, same form as from.

Responses

200SellerPerformanceResponse
StatusMeaning (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 error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/seller-performance' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

OMITTING 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

NameInTypeDescription
from
querystring

Start of the window, as a CALENDAR DAY (YYYY-MM-DD) in the workspace timezone, not an instant. Omit both bounds for all time.

to
querystring

End of the window, inclusive, same form as from.

channels
querystring | string[]

Restrict to one or more channels. One of tiktok, ebay, etsy, amazon. Repeat the parameter (?channels=tiktok&channels=ebay) or comma-join it (?channels=tiktok,ebay); both are accepted, and an unrecognised key is refused BY NAME rather than dropped.

shops
querystring | string[]

Restrict to one or more shops, in either of the two forms channels accepts. A key bound to specific shops is additionally constrained to its own binding, so naming a shop it was not issued for narrows the result rather than widening it.

seller
querystring

Restrict to orders attributed to one seller.

granularity
querystring

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

200RevenueSeriesResponse
StatusMeaning (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 error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/revenue-series' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/analytics/busiest-days

All 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

NameInTypeDescription
from
querystring

Start of the window, as a CALENDAR DAY (YYYY-MM-DD) in the workspace timezone, not an instant. Omit both bounds for all time.

to
querystring

End of the window, inclusive, same form as from.

channels
querystring | string[]

Restrict to one or more channels. One of tiktok, ebay, etsy, amazon. Repeat the parameter (?channels=tiktok&channels=ebay) or comma-join it (?channels=tiktok,ebay); both are accepted, and an unrecognised key is refused BY NAME rather than dropped.

shops
querystring | string[]

Restrict to one or more shops, in either of the two forms channels accepts. A key bound to specific shops is additionally constrained to its own binding, so naming a shop it was not issued for narrows the result rather than widening it.

seller
querystring

Restrict to orders attributed to one seller.

Responses

200BusiestDaysResponse
StatusMeaning (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 error.code).

422

The marketplace rejected the request; error.details carries its own message.

429

Back off and retry. error.code says whose limit was hit: rate_limited is ours (honour Retry-After), channel_rate_limited is the marketplace throttling us, channel_unavailable is the marketplace being unreachable.

500

A defect on our side (internal_error), and the only status left outside the 4xx range. The origin emits the envelope below, but the edge in front of api.doctorx.vn replaces the body of a 5xx with its own plain-text page, so do NOT require this body to parse: branch on the status.

Request sample

curl -X GET 'https://api.doctorx.vn/api/public/v1/analytics/busiest-days' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"