API reference

List paid orders (per-fan references)

Paid drop orders of the key's account, newest first — the polling twin of the [drop.paid webhook](/developers/webhooks/overview).

View as MarkdownUpdated Oct 17, 2026

GET/api/external/ordersNew

Paid drop orders of the key's account, newest first — the polling twin of the drop.paid webhook.

Filter by externalRef to answer "did this fan pay?" on a shared drop, or by productId / since to sweep. Refunded and charged-back orders stay in the list with their status — act on status: "paid" only.

Authentication

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

Query parameters

Name	Type	Required	Description
`productId`	string	Optional	Only orders for this drop.
`externalRef`	string	Optional	Only orders bought through links carrying this reference. Max length: 32 Pattern: `^[A-Za-z0-9_-]{1,32}$`
`since`	string	Optional	Only orders paid at or after this time. Format: date-time
`limit`	integer	Optional	Page size. Default: `50` Min: 1 Max: 100
`cursor`	string	Optional	`nextCursor` from the previous page.

Responses

200A page of orders.

Name Type Description

orders

Order[]

Newest first.

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.

nextCursor string | null Pass as cursor for the next page; null on the last page.

Example response

{
  "orders": [
    {
      "orderId": "clxor0001order",
      "productId": "clxdr0p000001prod",
      "accountId": "clx2f8a1b0001qw3k",
      "externalRef": "tg_48213377",
      "amountCents": 2750,
      "currency": "USD",
      "paidAt": "2026-10-17T16:20:00.000Z",
      "paidWith": "card",
      "status": "paid",
      "buyer": {
        "id": "clxbu0001buyer",
        "email": "[email protected]",
        "telegramUserId": "48213377",
        "telegramUsername": "fan_one"
      }
    }
  ],
  "nextCursor": null
}

Errors

Status	Body	When
400	`{"error":"externalRef must be 1–32 of A-Z a-z 0-9 _ -"}`	Malformed reference.
400	`{"error":"since must be an ISO date"}`	Unparseable `since`.
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.

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 "https://www.dropfans.io/api/external/orders?productId=clxdr0p000001prod&externalRef=tg_48213377" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"

const res = await fetch(`https://www.dropfans.io/api/external/orders?productId=clxdr0p000001prod&externalRef=tg_48213377`, {
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
  },
});
console.log(await res.json());

import os
import requests

res = requests.get(
    "https://www.dropfans.io/api/external/orders",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    params={"productId": "clxdr0p000001prod", "externalRef": "tg_48213377"},
)
print(res.json())

← Previous

Check which drops sold (batch)

Publish a post to the For You feed

Questions? [email protected]