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

Authentication

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

An agency's own key can call this for a creator it manages by adding X-Dropfans-Account: <account id> (needs canManageDrops). See Agencies.

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

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

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": "[email protected]"
    }
  },
  "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": "[email protected]",
          "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.
403	`{"error":"This key cannot act for that account.","code":"account_not_managed"}`	`X-Dropfans-Account` names an account this key cannot act for: not an agency’s own key, no ACCEPTED management, or the agency or account 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"}`	With `X-Dropfans-Account`: the agency lacks `canManageDrops` on that account.

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/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/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/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? [email protected]