API reference

Read back a drop

One drop you created: price, moderation status (overall and per media item), checkout URL, whether previews are attached, and a sales summary.

View as MarkdownUpdated Aug 19, 2026

GET/api/external/v1/drops/{id}also served at /api/external/drops/{id}New

One drop you created: price, moderation status (overall and per media item), checkout URL, whether previews are attached, and a sales summary.

salesCount counts paid orders excluding refunds and chargebacks — stricter than check-status, which does not exclude them. Use this endpoint to verify a drop went APPROVED before attaching it to a post, and to see which media items still lack a baked preview.

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

GET /api/external/v1/creators/{creatorId}/drops/{id} — 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.

Path parameters

Name	Type	Required	Description
`id`	string	Required	The product (drop) id from create-drop.

Responses

200The drop.

Name Type Description

id string The product (drop) id.

name string | null Drop title. Null when created without a name.

price number USD **dollars**. 0 means free.

currency

string

Always "USD".

One of: USD

status

string

The drop’s overall moderation status. A drop built from already-APPROVED vault items is APPROVED at creation.

One of: PENDING, APPROVED, REJECTED, FLAGGED

moderationReason string | null Why the drop was rejected or flagged. Null otherwise.

buyUrl

string

With an app key: your app’s plain buy link id (/buy/{linkId}) — created by POST /drops; reads return it when it exists, else /buy/{productId} (a drop your app created still counts for it). With a personal key: /buy/{productId}. For a per-fan reference, create a link with POST /api/external/v1/links.

Format: uri

linkId string | null The link id in buyUrl (app keys only); comes back as linkId on the sale.

allowDownload boolean Images only: whether buyers get a Download button serving a watermarked, metadata-stripped JPEG. Videos are never downloadable (DRM stream). Defaults to false.

mediaCount integer Number of media items attached.

media

object[]

Attached media in display order.

Show child attributes

`vaultItemId`	string	The source vault item.
`order`	integer	Display position (0-based).
`fileType`	string	Media kind. One of: `image`, `video`, `audio`
`moderationStatus`	string	Per-item moderation status. One of: `PENDING`, `APPROVED`, `REJECTED`, `FLAGGED`
`hasPreview`	boolean	True once a baked blur preview was attached via POST /api/external/v1/drops/{id}/previews.

salesCount integer Paid orders, excluding refunds and chargebacks (stricter than check-status, which does NOT exclude refunds).

lastSaleAt

string | null

When the newest counted sale was paid. Null when never sold.

Format: date-time

createdAt

string

Creation time.

Format: date-time

Example response

{
  "id": "clxdr0p000001prod",
  "name": "Beach set — 6 photos",
  "price": 25,
  "currency": "USD",
  "status": "APPROVED",
  "moderationReason": null,
  "buyUrl": "https://www.dropfans.io/buy/clxdr0p000001prod",
  "allowDownload": false,
  "mediaCount": 3,
  "media": [
    {
      "vaultItemId": "clxv1a2b30001item",
      "order": 0,
      "fileType": "image",
      "moderationStatus": "APPROVED",
      "hasPreview": true
    },
    {
      "vaultItemId": "clxv1a2b30002item",
      "order": 1,
      "fileType": "image",
      "moderationStatus": "APPROVED",
      "hasPreview": true
    },
    {
      "vaultItemId": "clxv1a2b30003item",
      "order": 2,
      "fileType": "video",
      "moderationStatus": "APPROVED",
      "hasPreview": false
    }
  ],
  "salesCount": 2,
  "lastSaleAt": "2026-08-18T21:03:00.000Z",
  "createdAt": "2026-08-15T09:00:00.000Z"
}

Errors

Status	Body	When
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.
404	`{"error":"Drop not found"}`	No such drop on this account (another creator’s drop also 404s — never 403).
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 "https://www.dropfans.io/api/external/v1/drops/$PRODUCT_ID" \
  -H "Authorization: Bearer $DROPFANS_API_KEY"

const productId = '…'; // from an earlier response

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

import os
import requests

product_id = "…"  # from an earlier response

res = requests.get(
    f"https://www.dropfans.io/api/external/v1/drops/{product_id}",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
)
print(res.json())

← Previous

List the creator’s drops

Edit a drop

Questions? support@dropfans.io