> ## Documentation Index > Fetch the complete documentation index at: https://www.dropfans.io/developers/llms.txt > Use this file to discover all available pages before exploring further. # POST /api/external/v1/drops/check-status — Check which drops sold (batch) > Sale info for a batch of product ids — the polling half of sale tracking. - Source: https://www.dropfans.io/developers/reference/check-drop-status - Section: API reference - OpenAPI: https://www.dropfans.io/developers/openapi.json Also served at `/api/external/drops/check-status` (the unversioned alias). Sale info for a batch of product ids — the polling half of sale tracking. Poll it periodically (every few minutes is plenty) with the productIds you are tracking. Amounts are gross buyer-paid totals in **cents**. `sales` keeps its original one-entry-per-product shape; `orders` lists **every** paid order per product with its per-fan `externalRef` — use that for shared drops (or the [drop.paid webhook](https://www.dropfans.io/developers/webhooks/overview.md)). > [!WARNING] Truncation, omission, refunds > At most 200 ids are processed per call — extras are **dropped without an error**, so chunk larger lists. Unsold and unknown ids are **omitted** from the response (only `paid: true` entries appear). And unlike earnings, this endpoint does **NOT exclude refunded or charged-back orders** — a refunded sale still reports paid. Reconcile against [GET /api/external/v1/earnings](https://www.dropfans.io/developers/reference/get-earnings.md) for net truth. ## Authentication `Authorization: Bearer dpfn_...` — an API key generated in the dashboard (Vault → API Connect). By default the key acts for the one account it belongs to. Missing or invalid keys return 401 `{"error":"Unauthorized","code":"unauthorized"}`. **For a creator you manage or onboarded:** `POST /api/external/v1/creators/{creatorId}/drops/check-status` — with a verified agency's own key for a creator or AI persona it manages, or your app owner's own key for an account your app onboarded (ids from GET /api/external/v1/creators); for a managed creator the agency needs `canManageDrops`. The response echoes the account acted on in `X-Dropfans-Account`. Sending `X-Dropfans-Account: ` on the plain path still works but is deprecated. ## Request body (application/json) | Field | Type | Required | Description | |---|---|---|---| | `productIds` | string[] | yes | Product ids to check (≤200 — extras silently dropped). Non-strings filtered out; an empty array returns {"sales":{}}. | Example — Check two drops: ```json { "productIds": [ "clxdr0p000001prod", "clxdr0p000002prod" ] } ``` ## Responses ### 200 Sales map — only sold products appear. Multiple paid orders on one product report the most recent. | Field | Type | Required | Description | |---|---|---|---| | `sales` | SalesMap | yes | productId → most recent sale. | | `orders` | OrdersByProduct | yes | productId → every paid order (newest first), each with its externalRef. Added 2026-10-17. | ```json { "sales": { "clxdr0p000001prod": { "paid": true, "saleAmountCents": 2500, "buyerEmail": "buyer@example.com" } }, "orders": { "clxdr0p000001prod": [ { "orderId": "clxor0001order", "productId": "clxdr0p000001prod", "accountId": "clx2f8a1b0001qw3k", "externalRef": "tg_48213377", "amountCents": 2500, "currency": "USD", "paidAt": "2026-10-17T16:20:00.000Z", "paidWith": "card", "status": "paid", "buyer": { "id": "clxbu0001buyer", "email": "buyer@example.com", "telegramUserId": "48213377", "telegramUsername": "fan_one" } } ] } } ``` ## Errors | Status | Body | When | |---|---|---| | 400 | `{"error":"Invalid JSON body"}` | The body is not valid JSON. | | 401 | `{"error":"Unauthorized","code":"unauthorized"}` | Missing or invalid API key. | | 500 | `{"error":"Failed to check drop status"}` | Query failed — retry later. | | 400 | `{"error":"X-Dropfans-Account must be an account id (from GET /api/external/agency/creators), not a username.","code":"invalid_account_header"}` | `X-Dropfans-Account` is not an account id. | | 400 | `{"error":"X-Dropfans-Account names a different account than the path — send one or the other.","code":"account_mismatch"}` | Called under /v1/creators/{creatorId}/ with an `X-Dropfans-Account` naming another account. | | 403 | `{"error":"This key cannot act for that account.","code":"account_not_managed"}` | The creator in the path (or `X-Dropfans-Account`) is one this key cannot act for: no ACCEPTED management by your agency and not an account your app onboarded (or it no longer holds a key bound to your app), a key minted for one creator, or someone is suspended, banned or deleted. An unknown id gets the same answer. | | 403 | `{"error":"The agency does not have permission for this on that account.","code":"permission_denied","permission":"canManageDrops"}` | For a managed creator: the agency lacks `canManageDrops` on that account. | | 403 | `{"error":"This app does not have the drops API category enabled. Contact support to enable it.","code":"api_category_disabled","category":"drops"}` | Your app has the Drops & checkout links [API category](https://www.dropfans.io/developers/concepts/api-categories.md) switched off. | ## Rate limiting Per-key fixed windows by tier (Personal 60/min · 5,000/day; approved apps 300/min · 50,000/day; Dropfans-operated integrations exempt). Read the live values from X-RateLimit-Tier, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and their -Day variants; a 429 carries Retry-After and `{"error":"Rate limit exceeded","code":"rate_limited"}`. See [Rate limits](https://www.dropfans.io/developers/concepts/rate-limits.md). ## Code samples ### curl ```bash curl -X POST "https://www.dropfans.io/api/external/v1/drops/check-status" \ -H "Authorization: Bearer $DROPFANS_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "productIds": [ "clxdr0p000001prod", "clxdr0p000002prod" ] }' ``` ### Node ```javascript const res = await fetch(`https://www.dropfans.io/api/external/v1/drops/check-status`, { method: 'POST', headers: { Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ "productIds": [ "clxdr0p000001prod", "clxdr0p000002prod" ] }), }); console.log(await res.json()); ``` ### Python ```python import os import requests res = requests.post( "https://www.dropfans.io/api/external/v1/drops/check-status", headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"}, json={ "productIds": [ "clxdr0p000001prod", "clxdr0p000002prod", ], }, ) print(res.json()) ``` ## OpenAPI ```json { "method": "POST", "path": "/api/external/v1/drops/check-status", "operationId": "checkDropStatus", "tags": [ "drops" ], "summary": "Check which drops sold (batch)", "description": "Sale info for a batch of product ids — the polling half of sale tracking.\n\nPoll it periodically (every few minutes is plenty) with the productIds you are tracking. Amounts are gross buyer-paid totals in **cents**. `sales` keeps its original one-entry-per-product shape; `orders` lists **every** paid order per product with its per-fan `externalRef` — use that for shared drops (or the [drop.paid webhook](https://www.dropfans.io/developers/webhooks/overview.md)).\n\n> [!WARNING] Truncation, omission, refunds\n> At most 200 ids are processed per call — extras are **dropped without an error**, so chunk larger lists. Unsold and unknown ids are **omitted** from the response (only `paid: true` entries appear). And unlike earnings, this endpoint does **NOT exclude refunded or charged-back orders** — a refunded sale still reports paid. Reconcile against [GET /api/external/v1/earnings](https://www.dropfans.io/developers/reference/get-earnings.md) for net truth.", "parameters": [ { "name": "X-Dropfans-Account", "in": "header", "required": false, "deprecated": true, "description": "Deprecated: call the …ForCreator operation (/api/external/v1/creators/{creatorId}/…) instead; the header keeps working and such responses carry Deprecation and Link: rel=\"successor-version\". With a verified agency’s own key, the id of a creator or AI persona the agency manages (from GET /api/external/v1/agency/creators): the request then acts as that account, exactly as if it were sent with that account’s own key. Account ids only — usernames are refused (400 invalid_account_header). Checked on every request: the management must be ACCEPTED, nobody may be suspended, banned or deleted (else 403 account_not_managed), and the agency needs the endpoint’s permission on that account (else 403 permission_denied). Omit it to act as the key’s own account.", "schema": { "type": "string", "pattern": "^c[a-z0-9]{20,32}$" }, "example": "cmh4v2q8k0003xy9z7w6v5u4t" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productIds": { "type": "array", "items": { "type": "string", "description": "A product id from create-drop." }, "description": "Product ids to check (≤200 — extras silently dropped). Non-strings filtered out; an empty array returns {\"sales\":{}}.", "maxItems": 200 } }, "required": [ "productIds" ] }, "examples": { "batch": { "summary": "Check two drops", "value": { "productIds": [ "clxdr0p000001prod", "clxdr0p000002prod" ] } } } } } }, "responses": { "200": { "description": "Sales map — only sold products appear. Multiple paid orders on one product report the most recent.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } }, "X-Dropfans-Account": { "description": "The id of the account this request acted on — the key’s own account, or the managed account named in the X-Dropfans-Account request header. Assert it when acting for several accounts.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "sales": { "type": "object", "description": "Keyed by the product ids you sent. Unsold and unknown ids are OMITTED — only entries with paid:true come back. Multiple paid orders on one product report the most recent. Refunded/charged-back orders are NOT excluded here (unlike earnings) — cross-check GET /api/external/v1/earnings for net truth.", "additionalProperties": { "type": "object", "properties": { "paid": { "type": "boolean", "description": "Always true — unsold products simply do not appear.", "example": true }, "saleAmountCents": { "type": "integer", "description": "Gross buyer-paid total in **cents** (order.totalCharged × 100).", "example": 2500 }, "buyerEmail": { "type": [ "string", "null" ], "description": "The buyer’s email when known, else null.", "format": "email" } }, "required": [ "paid", "saleAmountCents" ], "description": "Keyed by the product ids you sent. Unsold and unknown ids are OMITTED — only entries with paid:true come back. Multiple paid orders on one product report the most recent. Refunded/charged-back orders are NOT excluded here (unlike earnings) — cross-check GET /api/external/v1/earnings for net truth." }, "propertyNames": { "description": "Keys are the ids you sent ({productId})." } }, "orders": { "type": "object", "description": "Every paid order on that product, newest first — one entry per fan on a shared drop.", "additionalProperties": { "type": "array", "items": { "type": "object", "properties": { "orderId": { "type": "string", "description": "The order id. Unique per sale — dedupe on it.", "example": "clxor0001order" }, "productId": { "type": "string", "description": "The drop that was bought.", "example": "clxdr0p000001prod" }, "accountId": { "type": "string", "description": "The creator who sold it (the account behind the key).", "example": "clx2f8a1b0001qw3k" }, "externalRef": { "type": [ "string", "null" ], "description": "Your per-fan checkout reference from the link the buyer opened (`?m=` on the web, `b_{productId}_{ref}` in Telegram). Null when the buyer came without one. Not proof of identity — the buyer can edit the link.", "example": "tg_48213377", "maxLength": 32, "pattern": "^[A-Za-z0-9_-]{1,32}$" }, "linkId": { "type": [ "string", "null" ], "description": "The link id (POST /api/external/v1/links) it came through; null for template links. Its `externalRef` is the link’s.", "example": "q7m2c8zk4w" }, "amountCents": { "type": "integer", "description": "Gross buyer-paid total in **cents** (VAT included).", "example": 2750 }, "netAmountCents": { "type": "integer", "description": "What the creator keeps from this sale in **cents** (after the platform fee and VAT; before any agency split).", "example": 2000 }, "platformFeeCents": { "type": "integer", "description": "Platform fee in cents.", "example": 500 }, "taxCents": { "type": "integer", "description": "VAT in cents (retained, not paid out).", "example": 250 }, "currency": { "type": "string", "description": "Always USD.", "enum": [ "USD" ], "example": "USD" }, "paidAt": { "type": [ "string", "null" ], "description": "When the payment settled (UTC).", "format": "date-time" }, "paidWith": { "type": "string", "description": "Card, or the buyer’s prepaid wallet credits.", "enum": [ "card", "credits" ], "example": "card" }, "status": { "type": "string", "description": "Current state of the sale.", "enum": [ "paid", "refunded", "charged_back" ], "example": "paid" }, "buyer": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "description": "The buyer’s account id, when signed in." }, "email": { "type": [ "string", "null" ], "description": "Billing / account email.", "format": "email" }, "telegramUserId": { "type": [ "string", "null" ], "description": "Telegram user id (as a string) when the buyer used the Mini App — cross-check it against your externalRef.", "example": "48213377" }, "telegramUsername": { "type": [ "string", "null" ], "description": "Telegram @username without the @, when known." } }, "description": "Who paid. Every field may be null for a guest checkout." } }, "required": [ "orderId", "productId", "accountId", "amountCents", "netAmountCents", "platformFeeCents", "taxCents", "currency", "paidWith", "status", "buyer" ] }, "description": "Every paid order on that product, newest first — one entry per fan on a shared drop." }, "propertyNames": { "description": "Keys are the ids you sent ({productId})." } } }, "required": [ "sales", "orders" ] }, "example": { "sales": { "clxdr0p000001prod": { "paid": true, "saleAmountCents": 2500, "buyerEmail": "buyer@example.com" } }, "orders": { "clxdr0p000001prod": [ { "orderId": "clxor0001order", "productId": "clxdr0p000001prod", "accountId": "clx2f8a1b0001qw3k", "externalRef": "tg_48213377", "amountCents": 2500, "currency": "USD", "paidAt": "2026-10-17T16:20:00.000Z", "paidWith": "card", "status": "paid", "buyer": { "id": "clxbu0001buyer", "email": "buyer@example.com", "telegramUserId": "48213377", "telegramUsername": "fan_one" } } ] } } } } }, "400": { "description": "The body is not valid JSON. Also: `X-Dropfans-Account` is not an account id. Also: Called under /v1/creators/{creatorId}/ with an `X-Dropfans-Account` naming another account.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message describing what went wrong.", "example": "Vault item not found" } }, "required": [ "error" ] }, "example": { "error": "Invalid JSON body" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, api_category_disabled, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "The creator in the path (or `X-Dropfans-Account`) is one this key cannot act for: no ACCEPTED management by your agency and not an account your app onboarded (or it no longer holds a key bound to your app), a key minted for one creator, or someone is suspended, banned or deleted. An unknown id gets the same answer. Also: For a managed creator: the agency lacks `canManageDrops` on that account. Also: Your app has the Drops & checkout links [API category](https://www.dropfans.io/developers/concepts/api-categories.md) switched off.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, api_category_disabled, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "This key cannot act for that account.", "code": "account_not_managed" } } } }, "429": { "description": "Rate limit exceeded for the current minute or day window. Wait Retry-After seconds and retry.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying (sent with 429s).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, api_category_disabled, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "Rate limit exceeded", "code": "rate_limited" } } } }, "500": { "description": "Query failed — retry later.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message describing what went wrong.", "example": "Vault item not found" } }, "required": [ "error" ] }, "example": { "error": "Failed to check drop status" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "curl", "source": "curl -X POST \"https://www.dropfans.io/api/external/v1/drops/check-status\" \\\n -H \"Authorization: Bearer $DROPFANS_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"productIds\": [\n \"clxdr0p000001prod\",\n \"clxdr0p000002prod\"\n ]\n}'" }, { "lang": "JavaScript", "label": "Node", "source": "const res = await fetch(`https://www.dropfans.io/api/external/v1/drops/check-status`, {\n method: 'POST',\n headers: {\n Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n \"productIds\": [\n \"clxdr0p000001prod\",\n \"clxdr0p000002prod\"\n ]\n }),\n});\nconsole.log(await res.json());" }, { "lang": "Python", "source": "import os\nimport requests\n\nres = requests.post(\n \"https://www.dropfans.io/api/external/v1/drops/check-status\",\n headers={\"Authorization\": f\"Bearer {os.environ['DROPFANS_API_KEY']}\"},\n json={\n \"productIds\": [\n \"clxdr0p000001prod\",\n \"clxdr0p000002prod\",\n ],\n },\n)\nprint(res.json())" } ], "x-dropfans-docs": "https://www.dropfans.io/developers/reference/check-drop-status", "x-dropfans-category": "drops", "x-dropfans-agency-permission": "canManageDrops" } ``` --- Previous: [Attach baked blur previews to a drop](https://www.dropfans.io/developers/reference/attach-drop-previews.md) · Next: [List paid orders (per-fan references)](https://www.dropfans.io/developers/reference/list-orders.md) · All pages: [llms.txt](https://www.dropfans.io/developers/llms.txt)