DoctorX logoDoctorX Get an API key

Finance

Payouts, the funds summary, marketplace ledger entries and profit and loss.

GET/finances/payouts

Payouts DoctorX has synced from the marketplace, newest first, cursor-paginated over settledAt. A payout is invisible here until synced, so call POST /finances/sync first if a recent one is missing. status PROCESSING means the marketplace announced it but has not released the money.

Parameters

NameInTypeDescription
limit
queryinteger

Page size, 1..200. Defaults to 50.

min 1 · max 200 · default 50

cursor
querystring

Opaque cursor from a previous response meta.pagination.nextCursor.

order
querystring

Sort direction on the collection sort key.

One of: "asc", "desc"

default "desc"

includeTotal
querystring

When true, meta.pagination.total carries the full matching count (an extra COUNT query).

shopId
querystring

Restrict to one shop.

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

channel
querystring

Marketplace channel.

One of: "tiktok", "ebay", "etsy", "amazon"

status
querystring

One of: "PAID", "PROCESSING"

settledFrom
querystring (date-time) | string (date)

Inclusive lower bound on settledAt.

settledTo
querystring (date-time) | string (date)

Inclusive upper bound on settledAt.

updatedSince
querystring (date-time) | string (date)

Only payouts DoctorX wrote at or after this instant. Distinct from settledFrom, which filters on when the marketplace settled: a statement is re-pulled and re-reconciled after it first lands, so a feed keyed on the settlement date would never re-deliver a payout whose figures were later corrected.

sortBy
querystring

Sort key. Pair updatedAt with updatedSince.

One of: "settledAt", "updatedAt"

default "settledAt"

Responses

200PayoutListResponse
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/finances/payouts' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/finances/payouts/{id}

A single payout by DoctorX id, including its deductions split. Declared after the collection so payouts is not read as an id.

Parameters

NameInTypeDescription
idrequired
pathstring

Responses

200PayoutResponse
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/finances/payouts/string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/finances/ledger-entries

One Etsy or Amazon shop's individual money movements: every fee, tax, payment, refund and transaction with its own type code and signed amount, oldest first. This is where a marketplace fee actually is, as opposed to payouts, which for Etsy is a single figure built from exactly these rows. DoctorX keeps a copy of each shop's ledger, read from the marketplace every 6 hours and on POST /finances/sync, so an entry appears here within that window. Paging is a stable cursor: an Etsy shop runs by sequence, Etsy's own increasing number for each entry, so a cursor kept from the last page returns what was recorded since (the sequence can skip numbers, because not every number reaches DoctorX's copy of the ledger; an entry DoctorX receives later below a kept cursor is delivered by GET /changes/ledger-entries); an Amazon shop runs by occurredAt, and because an Amazon transaction can arrive about 48 hours after its date and later changes status, keep an Amazon ledger current with GET /changes/ledger-entries. classification is DoctorX's normalised reading (for Etsy the same one that attributes fees onto orders). eBay answers channel_not_supported: its payout statements are GET /finances/payouts.

Parameters

NameInTypeDescription
shopIdrequired
querystring

Required: one shop's ledger.

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

type
querystring

Only entries of this marketplace entry code (type), exactly.

min length 1 · max length 100

occurredFrom
querystring (date-time) | string (date)

Inclusive lower bound on occurredAt.

occurredTo
querystring (date-time) | string (date)

Inclusive upper bound on occurredAt.

search
querystring

Free-text match on the entry id and the marketplace ids it carries (entry, transaction, order, shipment), its type, group and description. Whitespace is collapsed and the term is folded, so the match is case- and accent-insensitive. Every word must match: more words narrow the result, they do not widen it. A word of letters matches at the start of a word in the text (dad matches Dad and Daddy, not Trinidad); a word containing a digit matches anywhere, so the tail of an order, tracking or SKU number still finds it. Punctuation separates words (t-shirt matches T-Shirt and t shirt). Wrap words in double quotes to require them adjacent. % and _ are not wildcards: punctuation only separates words, so a term of punctuation alone matches nothing.

limit
queryinteger

Entries per page, 1..100.

min 1 · max 100 · default 50

cursor
querystring

Opaque: pass back meta.pagination.nextCursor verbatim. The feed runs OLDEST FIRST: an Etsy shop by sequence, an Amazon shop by occurredAt. Etsy only ever appends, so a cursor kept from the last page returns exactly the entries recorded since. An Amazon transaction can arrive up to about 48 hours after its date and changes status later, so keep an Amazon ledger current with GET /changes/ledger-entries, which delivers both.

Responses

200LedgerEntryListResponse
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/finances/ledger-entries?shopId=string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/finances/ledger-entries/{id}

One entry by its id within its shop (shopId is required: an entry id is unique within its shop only). For an Amazon transaction the answer also carries its item lines and how its amount splits (items, breakdowns), read from the marketplace on this call; Etsy keeps no detail beyond the entry, so both are null there.

Parameters

NameInTypeDescription
idrequired
pathstring
shopIdrequired
querystring

Required: the entry's shop. An entry id is unique within its shop only.

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

Responses

200LedgerEntryDetailResponse
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/finances/ledger-entries/string?shopId=string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/finances/pnl/products

One Amazon shop's sales by product line (one line per ASIN and SKU, with the DoctorX product when DoctorX holds its listing) for a window of at most 366 days, counted in the shop's own time zone (timezone). NEVER WAITS: a window DoctorX does not hold yet answers state: not_ready at once and is read in the background (a year of the catalog takes about a minute); ask again after retryAfterSeconds. The last 12 months, 90 days, 30 days and this month are kept ready. Pages with cursor in a stable order. Amazon data lands about 48 hours late, so a window's last days can still move, and generatedAt says when the copy was read. The days are the shop's own, which can differ from GET /finances/pnl (that report counts days in New York time). Other channels answer channel_not_supported.

Parameters

NameInTypeDescription
shopIdrequired
querystring

An Amazon shop.

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

fromrequired
querystring

First day, YYYY-MM-DD, in the shop's own time zone, or in tz (timezone in the answer).

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

torequired
querystring

Last day, inclusive. The window is at most 366 days.

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

limit
queryinteger

Products per page, 1..200. Defaults to 50.

min 1 · max 200 · default 50

cursor
querystring

Opaque: pass back nextCursor verbatim for the next page of the same window.

tz
querystring

Count the days in this time zone (an IANA name such as Asia/Bangkok) instead of the shop's own. A zone other than the shop's is not kept ready, so its first request answers not_ready.

max length 64

Responses

200ProductPnlResponse
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/finances/pnl/products?shopId=string&from=string&to=string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/finances/pnl

One Amazon shop's profit and loss for a window of at most 366 days, from the marketplace connection's own report, in USD: sales, advertising, Amazon's fees (27 lines), refunds, other charges, cost of goods, payout and profit, for the whole window and for each period, NEWEST FIRST. COSTS ARE POSITIVE EVERYWHERE (signConvention: costs_positive): in the totals, every period and every breakdown line, where a credit such as a reimbursement is negative, so each breakdown sums to its headline. Days are the marketplace's own (timezone). Periods are days, ISO weeks (Monday first), months, quarters or years, clipped to the window; a window that would need more than 31 periods is answered at the next coarser size (granularityAdjusted). A ratio the report cannot compute is null, never 0. Amazon data lands about 48 hours after the fact, so the last days of a window can still move; a period that ended more than 3 days ago is answered from a copy kept for a day, a recent one from a copy kept for 15 minutes. Other channels answer channel_not_supported.

Parameters

NameInTypeDescription
shopIdrequired
querystring

An Amazon shop.

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

fromrequired
querystring

First day, YYYY-MM-DD, in the marketplace time zone.

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

torequired
querystring

Last day, inclusive. The window is at most 366 days.

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

granularity
querystring

Period size. Weeks are ISO weeks (Monday first), clipped to the window. Coarsened when the window would need more than 31 periods.

One of: "day", "week", "month", "quarter", "year"

default "month"

Responses

200PnlResponse
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/finances/pnl?shopId=string&from=string&to=string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"
GET/finances/funds-summary

Read LIVE from the marketplace, not from a cached column, so it cannot be stale. This is the same source as balance on GET /authorize/shops: the two are the same numbers by construction rather than by convention, so do not treat them as independent figures to reconcile.

Parameters

NameInTypeDescription
shopIdrequired
querystring

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

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

Responses

200FundsSummaryResponse
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/finances/funds-summary?shopId=string' \
  -H "Authorization: Bearer $DOCTORX_API_KEY"

Asks the marketplace for recent payouts and stores what it returns. Creates no figures of its own. Idempotent by marketplace payout id, so repeating it is safe. Defaults to the adapter window (90 days for eBay); sinceDays widens or narrows it. For an Etsy or Amazon shop it also asks for the shop's ledger (GET /finances/ledger-entries) to be read now: that read runs in the background, never inside this request, and ledger says what became of the request. pulled is 0 for both: Etsy's payout is rebuilt from that ledger when it is read, and Amazon has no payout statements. For an Amazon shop it also asks for its orders' marketplace fees to be read again for the months sinceDays covers (the current and the previous month by default), and orderFees says what became of that. Because this WRITES, it also needs the shop channel's write scope (ebay:write, etsy:write or amazon:write) alongside finances:read.

Request body

shopIdstringrequired

DoctorX resource id: a UUID in canonical 8-4-4-4-12 hex form. Version and variant bits are not constrained.

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

sinceDaysinteger

How far back to ask the marketplace. Defaults to the adapter window (90 days for eBay). For an Amazon shop it also sets how far back its orders' marketplace fees are read again, by calendar month: the months from the one sinceDays ago to the current one (the current and the previous month without it).

min 1 · max 365

Responses

200FinanceSyncResultResponse
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 POST 'https://api.doctorx.vn/api/public/v1/finances/sync' \
  -H "Authorization: Bearer $DOCTORX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "shopId": "string"
}'