API reference

Check which drops sold (batch)

Sale info for a batch of product ids — the polling half of sale tracking.

View as MarkdownUpdated Aug 19, 2026

POST/api/external/v1/drops/check-statusalso served at /api/external/drops/check-status

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).

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 for net truth.

Authentication

Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.

For a creator you manage or onboarded

POST /api/external/v1/creators/{creatorId}/drops/check-status — an agency's own key for a creator or AI persona it manages (needs canManageDrops), or your app owner's own key for an account your app onboarded. The X-Dropfans-Account header still works but is deprecated. See Acting for a creator.

Request body

Content type: application/json

Name	Type	Required	Description
`productIds`	string[]	Required	Product ids to check (≤200 — extras silently dropped). Non-strings filtered out; an empty array returns {"sales":{}}. Max items: 200

Check two drops

{
  "productIds": [
    "clxdr0p000001prod",
    "clxdr0p000002prod"
  ]
}

Responses

200Sales map — only sold products appear. Multiple paid orders on one product report the most recent.

Name Type Description

sales

SalesMap

productId → most recent sale.

Show child attributes

{productId}

object

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.

Show child attributes

`paid`	boolean	Always true — unsold products simply do not appear.
`saleAmountCents`	integer	Gross buyer-paid total in cents (order.totalCharged × 100).
`buyerEmail`	string \| null	The buyer’s email when known, else null. Format: email

orders

OrdersByProduct

productId → every paid order (newest first), each with its externalRef. Added 2026-10-17.

Show child attributes

{productId}

Order[]

Every paid order on that product, newest first — one entry per fan on a shared drop.

Show child attributes

orderId string The order id. Unique per sale — dedupe on it.

productId string The drop that was bought.

accountId string The creator who sold it (the account behind the key).

externalRef

string | null

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.

Max length: 32

Pattern: ^[A-Za-z0-9_-]{1,32}$

linkId string | null The link id (POST /api/external/v1/links) it came through; null for template links. Its externalRef is the link’s.

amountCents integer Gross buyer-paid total in **cents** (VAT included).

netAmountCents integer What the creator keeps from this sale in **cents** (after the platform fee and VAT; before any agency split).

platformFeeCents integer Platform fee in cents.

taxCents integer VAT in cents (retained, not paid out).

currency

string

Always USD.

One of: USD

paidAt

string | null

When the payment settled (UTC).

Format: date-time

paidWith

string

Card, or the buyer’s prepaid wallet credits.

One of: card, credits

status

string

Current state of the sale.

One of: paid, refunded, charged_back

buyer

object

Who paid. Every field may be null for a guest checkout.

Show child attributes

`id`	string \| null	The buyer’s account id, when signed in.
`email`	string \| null	Billing / account email. Format: email
`telegramUserId`	string \| null	Telegram user id (as a string) when the buyer used the Mini App — cross-check it against your externalRef.
`telegramUsername`	string \| null	Telegram @username without the @, when known.

Example response

{
  "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](/developers/concepts/api-categories) switched off.

Rate limiting

Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.

Code samples

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"
  ]
}'

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());

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())

← Previous

Attach baked blur previews to a drop

List paid orders (per-fan references)

Questions? support@dropfans.io