Finance
Payouts, the funds summary, marketplace ledger entries and profit and loss.
/finances/payoutsPayouts 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
| Name | In | Type | Description |
|---|---|---|---|
limit | query | integer | Page size, 1..200. Defaults to 50. min 1 · max 200 · default 50 |
cursor | query | string | Opaque cursor from a previous response meta.pagination.nextCursor. |
order | query | string | Sort direction on the collection sort key. One of: "asc", "desc" default "desc" |
includeTotal | query | string | When true, meta.pagination.total carries the full matching count (an extra COUNT query). |
shopId | query | string | 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 | query | string | Marketplace channel. One of: "tiktok", "ebay", "etsy", "amazon" |
status | query | string | One of: "PAID", "PROCESSING" |
settledFrom | query | string (date-time) | string (date) | Inclusive lower bound on settledAt. |
settledTo | query | string (date-time) | string (date) | Inclusive upper bound on settledAt. |
updatedSince | query | string (date-time) | string (date) | Only payouts DoctorX wrote at or after this instant. Distinct from |
sortBy | query | string | Sort key. Pair One of: "settledAt", "updatedAt" default "settledAt" |
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/finances/payouts' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string |
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/finances/payouts/string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/finances/ledger-entriesOne 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
| Name | In | Type | Description |
|---|---|---|---|
shopIdrequired | query | string | 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 | query | string | Only entries of this marketplace entry code ( min length 1 · max length 100 |
occurredFrom | query | string (date-time) | string (date) | Inclusive lower bound on |
occurredTo | query | string (date-time) | string (date) | Inclusive upper bound on |
search | query | string | 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 ( |
limit | query | integer | Entries per page, 1..100. min 1 · max 100 · default 50 |
cursor | query | string | Opaque: pass back |
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/finances/ledger-entries?shopId=string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/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
| Name | In | Type | Description |
|---|---|---|---|
idrequired | path | string | |
shopIdrequired | query | string | 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
| 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/finances/ledger-entries/string?shopId=string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/finances/pnl/productsOne 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
| Name | In | Type | Description |
|---|---|---|---|
shopIdrequired | query | string | 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 | query | string | First day, pattern ^\d{4}-\d{2}-\d{2}$ |
torequired | query | string | Last day, inclusive. The window is at most 366 days. pattern ^\d{4}-\d{2}-\d{2}$ |
limit | query | integer | Products per page, 1..200. Defaults to 50. min 1 · max 200 · default 50 |
cursor | query | string | Opaque: pass back |
tz | query | string | Count the days in this time zone (an IANA name such as max length 64 |
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/finances/pnl/products?shopId=string&from=string&to=string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/finances/pnlOne 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
| Name | In | Type | Description |
|---|---|---|---|
shopIdrequired | query | string | 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 | query | string | First day, pattern ^\d{4}-\d{2}-\d{2}$ |
torequired | query | string | Last day, inclusive. The window is at most 366 days. pattern ^\d{4}-\d{2}-\d{2}$ |
granularity | query | string | 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
| 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/finances/pnl?shopId=string&from=string&to=string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/finances/funds-summaryRead 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
| Name | In | Type | Description |
|---|---|---|---|
shopIdrequired | query | string | 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
| 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/finances/funds-summary?shopId=string' \
-H "Authorization: Bearer $DOCTORX_API_KEY"/finances/syncAsks 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
shopIdstringrequiredDoctorX 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}$
sinceDaysintegerHow 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
| 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 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"
}'