Dropp Public API & Webhooks

All API endpoints require a Bearer token:

Authorization: Bearer drp_live_...

Pick the credential by what you are building:

Creating an API key

1. Go to Settings → API in your dashboard
2. Click Create Key
3. Choose a name, select scopes, and optionally restrict by IP
4. Copy the key — it's only shown once

Keys can be restricted to an IP allowlist: IPv4 addresses or CIDR ranges (for example 203.0.113.42 or 10.0.0.0/8). Requests from outside the allowlist receive 403 forbidden.

Test mode (drp_test_ keys)

Tick Test mode in the Create Key dialog (Settings → API → Create Key) to mint a drp_test_… key. It uses the same endpoints, scopes and base URL as a live key, but it lives in a separate partition of your account, Stripe-style:

Test cards on a sandbox checkout: Shift4 4242 4242 4242 4242 (any future expiry, any CVC); Nuvei 4000027891380961 (declined 4000020000000000, 3-D Secure challenge 4000023104662535). Which provider a checkout runs on depends on the creator's payment setup; both test cards are safe to try.

A typical dry run: create a test key with links:write, orders:read and webhooks:write → register a webhook endpoint with it → POST /v1/links (or /v1/donation-links) → open the returned checkout_url and pay with a test card → your endpoint receives order.paid with livemode: false, and GET /v1/orders with the test key lists the order. Repeat with your live key on a real purchase before going live.

Test keys have their own limit of 10 active keys per account, and a key's mode never changes: mint a live key when you go live. Test data is never deleted automatically, so name test links clearly.

Login with dropp (OAuth) — for tools serving multiple creators

If you build a product that many creators connect to, don't ask each of them to paste an API key. Register your app with dropp once (contact us — you receive a client_id, plus a client_secret for server-side apps), and creators connect with one click instead. The summary below is the short version; the full OAuth guide covers PKCE, token refresh and revocation in detail.

Step 1 — send the creator to the authorization URL (PKCE required, S256):

https://auth.dropp.fans/auth/v1/oauth/authorize
  ?response_type=code
  &client_id=<YOUR_CLIENT_ID>
  &redirect_uri=<YOUR_REGISTERED_REDIRECT_URI>
  &code_challenge=<S256(code_verifier)>
  &code_challenge_method=S256
  &state=<random>

Step 2 — they log in, see your app's name and the exact scopes it was registered with, and approve. dropp redirects back with ?code=...&state=....

Step 3 — exchange the code server-side at POST https://auth.dropp.fans/auth/v1/oauth/token (grant_type=authorization_code, with your code_verifier). You receive an access_token (~1 h) and a rotating refresh_token — always store the newest one.

Step 4 — call the API with it. Same endpoints, same shapes:

curl https://api.external.dropp.fans/v1/me -H "Authorization: Bearer <access_token>"

Every call is scoped to the creator who connected: reads return their data, writes act on their behalf. Read effective_profile_id from GET /v1/me to know who that is.

Single-creator and multi-creator apps

Every registered app is either single-creator or multi-creator. You start single-creator; the flip is one-way and we only do it when you ask.

• Single-creator. One creator connects and every call on their token is scoped to them. profile_id is optional, and accepted whenever it equals the connected creator.
• Multi-creator. An agency owner delegates a whole roster in one consent, and one token acts for many creators. There is no default identity — a scoped call that names nobody fails with 400 ambiguous_scope.

Because an explicit profile_id is accepted in both modes, send it on every scoped call from day one and the flip is a no-op deploy. The query string works on every endpoint; the body only on endpoints that declare it.

Grant lifecycle webhooks

We can register an events webhook URL on your app (contact us; you receive its signing secret once). It gets a POST for app.grant.created, app.grant.updated and app.grant.revoked when a creator connects, changes, or disconnects your app. The envelope is { id, event, created_at, data }, with data carrying grant_id, profile_id, status (active / pending / revoked) and, on revoke, reason (approver_revoked, creator_revoked or membership_lost). Signature headers are the same as domain webhooks. Delivery is best-effort (3 quick attempts, no delivery log, no retry API) — treat it as a hint and reconcile against connected_creators from GET /v1/me.

Partner app identification (X-Dropp-App-Key)

If your users bring their own dropp API keys and you don't implement OAuth, we can register your app and issue an app credential instead. Send it on every request alongside the user's key:

Authorization: Bearer drp_live_<the creator's own key>
X-Dropp-App-Key: drp_app_live_<your app credential>

The app key identifies your application, not a user — scopes and data access always come from the Authorization key. The app key unlocks partner-tier rate limits and per-app support diagnostics. It is a server-side secret: never ship it in a browser or public repo (we rotate it instantly if it leaks). An invalid app key fails the request — it is never silently ignored.

https://api.external.dropp.fans/v1

Everything is a REST API over HTTPS with JSON bodies. Money amounts are always integer cents (1990 is €19.90) — see the known issue on Orders — and timestamps are ISO-8601 in UTC.

Headers

Send an Idempotency-Key on every create call — links, copies, donation links, wishlists and creators. A network timeout then replays safely instead of racing. A conflicting use of the same key returns 409.

Acting for a creator (profile_id)

Agency keys and multi-creator OAuth apps act for more than one creator, so scoped calls name the creator with profile_id:

• Query string works on every endpoint. When in doubt, use it.
• Body is accepted only on the endpoints that declare it, such as POST /v1/links and POST /v1/content/upload-url.
• Endpoints that don't declare it in the body — POST /v1/links/{id}/copies, POST /v1/links/{id}/vault-link — reject it there with 400. Use the query string.

List the creators you can act for with GET /v1/creators.

Pagination

All list endpoints use cursor-based pagination:

{
  "data": [],
  "pagination": {
    "has_more": true,
    "next_cursor": "item_id_here"
  }
}

Pass ?cursor=<next_cursor>&limit=25 to fetch the next page. The default limit is 25, the maximum 100. Stop when has_more is false.

Rate limit status is returned in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. A 429 carries Retry-After in seconds.

Registered partner apps

Traffic from a registered app — OAuth tokens, or a user's key sent with your X-Dropp-App-Key — is checked at two levels:

Registrations can carry higher limits — contact us when you need more; no client change is required. Requests sent without your app key still work, but fall back to the default per-key limits and aren't attributed to your app.

On 429, branch on error.code, never on the message:

• rate_limited — one creator's budget. Back off for that creator only.
• app_rate_limited — your app's shared ceiling. Apply one global throttle to the whole integration; per-creator backoff won't help.

Creator provisioning

POST /v1/agency/creators has its own budgets, counted per agency rather than per key: 30/hour and 200/day, plus a 300/hour aggregate for registered partner apps. Rejected addresses cost budget too — the windows are charged on attempt, not on success — and 409 email_unavailable carries a separate, much tighter budget (20/hour), so it is not a signal to iterate over addresses.

These budgets are fail-closed: if the limiter is unavailable, the endpoint refuses with 503 rather than creating accounts unmetered. Retry with backoff.

Video uploads

Video uploads have separate budgets because each video costs transcoding and storage: by default 100/hour and 500/week per creator, plus an app-wide ceiling of 1000/hour for partner apps. Image uploads have no upload budget.

Every video upload response reports the budget left after that upload:

{
  "data": {
    "content_id": "ctt_abc123",
    "upload_url": "https://…",
    "upload_budget": {
      "per_hour": { "limit": 100, "remaining": 82, "reset_in_seconds": 1080 },
      "per_week": { "limit": 500, "remaining": 444, "reset_in_seconds": 302400 },
      "app_per_hour": { "limit": 1000, "remaining": 613, "reset_in_seconds": 1080 }
    }
  }
}

app_per_hour appears only for partner-app traffic and is shared by every creator connected to your app, so per-creator budgets alone can't predict it. Run one global pacer for app_per_hour plus a pacer per creator for the other windows.

Login with dropp lets creators connect their dropp account to your product with one click: they approve the scopes your app registered, you get short-lived tokens scoped to them, and they can disconnect you at any time. This guide walks through the full authorization code flow with PKCE, from registration to handling a revoked grant.

How Login with dropp works

Login with dropp is standard OAuth 2.1 with PKCE. The authorization server lives at https://auth.dropp.fans; the tokens it issues are used against the API at https://api.external.dropp.fans/v1.

1. Your server generates a PKCE verifier and a state value, then redirects the creator to the authorize URL.
2. The creator logs in to dropp, sees your app's name and scopes, and approves.
3. dropp redirects back to your redirect_uri with a one-time code.
4. Your server exchanges the code (plus the verifier) for an access token and a refresh token.
5. You call the API with Authorization: Bearer <access_token> and refresh when it expires.

The token only works against the dropp public API. It is not a dropp session: dashboard surfaces refuse it.

Registering your OAuth app

Registration is manual for now. Contact us with your app name, homepage, a contact email, the scopes you need and your redirect URIs. You receive:

Public clients (a native or single-page app with no backend) get no client_secret and rely on PKCE alone. Confidential clients send the secret in the token request body.

Redirect URIs must be https:// with no #fragment. The only exception is http://localhost, 127.0.0.1 or [::1] for local development. The redirect_uri you send must exactly match one you registered.

Step 1: Generating a PKCE verifier and challenge

PKCE is mandatory and only S256 is accepted. For every connection attempt, generate a fresh random code_verifier, derive the code_challenge from it, and keep the verifier and state server-side (for example in a short-lived, encrypted, httpOnly cookie) until the creator comes back.

import { createHash, randomBytes } from "node:crypto";

const codeVerifier = randomBytes(32).toString("base64url"); // 43 chars
const codeChallenge = createHash("sha256")
  .update(codeVerifier)
  .digest("base64url"); // BASE64URL(SHA256(verifier)), no padding
const state = randomBytes(16).toString("base64url");

// Persist { codeVerifier, state, redirectUri } for ~10 minutes,
// bound to this browser session.

Step 2: Sending the creator to the authorize URL

Redirect the creator's browser to:

https://auth.dropp.fans/auth/v1/oauth/authorize
  ?response_type=code
  &client_id=<YOUR_CLIENT_ID>
  &redirect_uri=<URL-encoded YOUR_REGISTERED_REDIRECT_URI>
  &code_challenge=<codeChallenge>
  &code_challenge_method=S256
  &state=<state>

There is no scope parameter: the consent screen always shows the scope set your app was registered with.

The creator logs in if needed, then approves. A creator who administers an agency also sees a picker to connect creators from their roster. See Preparing for the multi-creator flip.

Step 3: Handling the redirect back

dropp redirects the browser to your redirect_uri:

https://yourapp.example/oauth/callback?code=<one-time code>&state=<state>

Before doing anything else:

• Verify state against the value you stored. On a mismatch, or if you have no stored transaction, stop and don't exchange the code.
• Handle a declined consent. If the creator declines, you get ?error=access_denied and no code. Show a "connection cancelled" state and don't retry automatically.
• Use the code once, and promptly. It is single-use and short-lived. Clear your stored transaction as soon as you read it.

Step 4: Exchanging the code for tokens

Exchange the code from your server, never from the browser. The body is form-encoded:

curl -X POST https://auth.dropp.fans/auth/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=<code> \
  -d redirect_uri=<YOUR_REGISTERED_REDIRECT_URI> \
  -d client_id=<YOUR_CLIENT_ID> \
  -d client_secret=<YOUR_CLIENT_SECRET> \
  -d code_verifier=<codeVerifier>

• redirect_uri must be the same value you sent to /authorize.
• client_secret goes in the form body: confidential clients are registered for client_secret_post. Public clients omit it.

The JSON response carries an access_token and a refresh_token:

Right after the exchange, call GET /v1/me to learn which app and creator the token maps to, and store the creator's effective_profile_id next to the tokens.

Refreshing and rotating tokens

When the access token expires, the API answers 401. Get a new pair from the same token endpoint:

curl -X POST https://auth.dropp.fans/auth/v1/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=refresh_token \
  -d refresh_token=<the latest refresh_token> \
  -d client_id=<YOUR_CLIENT_ID> \
  -d client_secret=<YOUR_CLIENT_SECRET>

Refresh tokens rotate. Every successful refresh returns a new refresh_token: store it at once and treat the old one as dead. In practice:

• Refresh on 401, then retry once. Or refresh ahead of time, a few minutes before the hour is up.
• Serialise refreshes per connection. If two workers refresh with the same refresh token, one of them loses. Use a lock per creator connection, or route refreshes through a single place.
• If the refresh is rejected, the grant is gone. The creator disconnected you. Clear the stored tokens and show a "Reconnect dropp" action instead of retrying.

async function droppFetch(conn, path, init = {}) {
  const call = (token) =>
    fetch(`https://api.external.dropp.fans/v1${path}`, {
      ...init,
      headers: { ...init.headers, Authorization: `Bearer ${token}` },
    });

  let res = await call(conn.accessToken);
  if (res.status !== 401) return res;

  const tokens = await refresh(conn.refreshToken); // POST /oauth/token, grant_type=refresh_token
  if (!tokens) {
    await markDisconnected(conn); // clear tokens, prompt the creator to reconnect
    throw new Error("dropp connection revoked");
  }
  await saveTokens(conn, tokens.access_token, tokens.refresh_token);
  res = await call(tokens.access_token);
  if (res.status === 401) await markDisconnected(conn);
  return res;
}

Storing OAuth tokens safely

• Keep client_secret, access tokens and refresh tokens server-side only: no browser bundles, mobile apps, logs or public repositories.
• Encrypt refresh tokens at rest. Key them by your own user and the dropp creator (effective_profile_id), so one of your users can hold several dropp connections.
• Store the token pair atomically. Writing a new access token next to an old refresh token breaks the next refresh.
• If your client_secret leaks, contact us right away so we can rotate your client credentials.

Calling the API with an access token

The endpoints and response shapes are the same as with an API key:

curl https://api.external.dropp.fans/v1/links?profile_id=pfl_abc123 \
  -H "Authorization: Bearer <access_token>"

Every call acts for exactly one creator. On a single-creator app, that is the creator who connected, so profile_id is optional. Send it anyway (see Preparing for the multi-creator flip). Put profile_id in the query string, which works on every endpoint, or in the body where an endpoint declares it. If you send both, they must be equal, or the call fails with 400 bad_request.

Your traffic is attributed to your app. Each connected creator has their own budget, and your app also has an aggregate ceiling. See Rate Limits.

Consent and scope snapshots

When a creator approves, their grant records your app's scope set at that moment. From then on, what a token can do is the intersection of that snapshot and your app's current registration:

Getting new scopes onto existing connections

Sending a creator through /authorize again does not refresh their snapshot, because repeat authorizations are auto-approved. To pick up a new scope, the creator has to disconnect your app in Settings → API → Connected Apps and connect again.

Use scopes_stale: true on a connected_creators row in GET /v1/me to find the creators who need it. Then show them a "Reconnect to enable …" prompt instead of failing silently.

Disconnects and revoked grants

Creators can disconnect your app at any time from Settings → API → Connected Apps. Disconnecting kills your tokens and refresh tokens immediately, not when the access token expires.

Don't retry in a loop on any of these, because they aren't transient. With an events webhook registered, you also get app.grant.revoked (with a reason) close to real time. Delivery is best-effort, so reconcile against GET /v1/me as well.

Preparing for the multi-creator flip

Every app starts single-creator: the token acts for the creator who connected. On request, we flip an app to multi-creator, where an agency admin can connect a whole roster in one consent and a single token acts for many creators. The flip is one-way and changes identity resolution on every request:

To make the flip a no-op deploy:

• Send profile_id on every scoped call from day one. It is accepted in both modes.
• Type effective_profile_id as nullable.
• Build your creator list from connected_creators in GET /v1/me. Keep rows where status is active, and read granted_via_agency to tell a creator who connected themselves from one an agency delegated. When an agency delegated the creator, their money may be held by the agency. See Account.
• Never send an agency id as profile_id. It returns 403 profile_not_connected.

On a single-creator app, an agency admin who connects only other creators produces an install with nothing callable. Every call returns 403 no_active_grant until the creator connects themselves or we flip your app. At the flip, pending delegated grants become active.

Two limits on the agency side: one install can connect at most 200 creators (grant_limit_reached). A creator who removes an agency-delegated connection also blocks the agency from re-adding them until the creator lifts the block.

OAuth errors to handle

API errors use the standard error envelope. Branch on error.code:

On the OAuth redirect and the token endpoint, handle error=access_denied (the creator declined) and a failed code exchange (the code expired or was reused, or the redirect_uri, code_verifier or client credentials are wrong). For a failed exchange, start a new authorization with a fresh verifier and state.

OAuth security checklist

• PKCE S256 and a checked state on every authorization.
• Code exchange and refresh on your server. The browser never sees client_secret or tokens.
• Only exact, https:// redirect URIs registered with us.
• Refresh tokens rotated and stored atomically, with one refresh in flight per connection.
• 401 handled as "refresh once, then reconnect", never as a retry loop.

Approved affiliate partners can create a dropp seller account through the API with their referral code already attached. You earn referral giveback on that seller's future sales, just as if they had signed up with your code on the site, without relying on ?ref= links.

When to provision a referred seller

Use POST /v1/creators when you bring a new seller to dropp and want the attribution to be certain from the start. For example, you might onboard creators in your own product and open their dropp account as part of that flow.

It is the wrong tool when:

• You are an agency adding your own talent. Use POST /v1/agency/creators with your agency API key instead. The creator joins your agency on a revenue split. See Account.
• The seller already has a dropp account. Provisioning never re-attributes an existing account, so the call changes nothing (see Provisioning response and statuses). Ask them to connect your app with Login with dropp instead.

Provisioning prerequisites

Both of these are set up by dropp when you are onboarded as an affiliate. You can't set them up yourself, because they decide where money is attributed:

You also need your App Key (drp_app_live_…). Contact us if you don't have one yet.

Calling POST /v1/creators

Every other endpoint acts for a creator. Here there is no account yet, so your App Key authenticates the call by itself. Send X-Dropp-App-Key and no Authorization header:

POST /v1/creators HTTP/1.1
Host: api.external.dropp.fans
X-Dropp-App-Key: drp_app_live_...
Content-Type: application/json
Idempotency-Key: 3f1c9a52-8d0e-4c7b-9a51-2b6f0e4d7c11

Provisioning a creator account

curl -X POST https://api.external.dropp.fans/v1/creators \
  -H "X-Dropp-App-Key: $APP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "email": "new.creator@example.com",
    "first_name": "Ava",
    "last_name": "Stone"
  }'

Provisioning an agency account

Set type to AGENCY when the seller you're referring will manage other creators. This creates an agency with the invited person as its ADMIN. You are not a member of it.

curl -X POST https://api.external.dropp.fans/v1/creators \
  -H "X-Dropp-App-Key: $APP_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "email": "owner@aurora.example",
    "type": "AGENCY",
    "agency_name": "Aurora Talent"
  }'

Provisioning request fields

You can never attribute a seller to any code except your app's bound code. The body is only there so you can assert it.

Provisioning response and statuses

Both outcomes return 201:

{
  "profile_id": "pfl_abc123",
  "email": "new.creator@example.com",
  "type": "CREATOR",
  "agency_id": null,
  "status": "provisioned",
  "referral_code": "D59638",
  "referral_claimed": true
}

A seller keeps the referral they first signed up under. already_exists doesn't tell you who that is, and you can't claim someone else's seller.

Retrying provisioning safely

Always send an Idempotency-Key (a UUID per new seller, up to 255 characters). Keys are scoped to your app:

Without a key, a retry after a timeout still won't create a second account: the email already exists, so you get already_exists with referral_claimed: false. The account and the install from your first call remain valid, but that response hides them. That is why the key matters.

After provisioning: invite, KYC and ownership

• The person takes the account over by email. dropp is passwordless: the invite link is how they log in for the first time. They then verify their email and finish onboarding (name, KYC, payout details).
• They can't sell until KYC passes. Until a real person takes the account over, it is inert. An unclaimed invite costs nothing, and your giveback accrues only on real, paid sales.
• They own the account, not you. For an AGENCY, the invited person is its ADMIN. They can revoke your app's access at any time (see below).

Acting as a provisioned creator

Provisioning also creates an install: your app can act as that creator with the same X-Dropp-App-Key and no Bearer token, as long as you name them with profile_id. The rules are in Account. A few points matter for planning:

• Only accounts that were provisioned by your app. An already_exists response creates no install. A creator who connected through Login with dropp is reachable with their OAuth token, not with your App Key.
• Scopes are fixed when you provision. The install carries your app's creator-facing scopes at that moment (never creators:provision), narrowed by any scope we later remove from your app. A scope added to your app later doesn't reach installs created earlier. Ask for the scopes you need before you start provisioning.
• Revocation is final for your app. The install appears in the creator's Settings → API → Connected Apps. If they remove it, every later call returns 403 profile_not_connected. Treat that as "this creator is no longer mine", not as a retryable error. If you registered an events webhook, you also get app.grant.revoked. No app.grant.created is sent for installs, so the 201 response is your record.

Provisioning budgets

POST /v1/creators is rate-limited as your app's own traffic, not per agency:

A 429 carries Retry-After. Branch on rate_limited or app_rate_limited as described in Rate Limits. The 30/hour and 200/day budgets on that page belong to POST /v1/agency/creators and don't apply here. Need more for a bulk import? Contact us.

Provisioning errors

409 email_unavailable, 502 provisioning_failed and 503 invites_unavailable in the error reference belong to POST /v1/agency/creators. This endpoint never returns them: an existing email is a 201 with already_exists.

Calls you make as a provisioned creator can also return 400 ambiguous_scope (no profile_id) and 403 profile_not_connected (not your install, or revoked).

Referral attribution FAQ

Can I attribute an existing account to my code? No. already_exists never re-attributes. This protects every referrer's earnings.

Do I become the seller's agency or owner? No. You get referral giveback only: no ownership and no revenue split. If you need an ownership relationship, that is a different onboarding. Contact us.

What if I don't send referral_code? Your app's bound code is used. Sending it only asserts which code you expect.

Sell a payment link inside Telegram, without the buyer ever leaving the app. One API call returns a ready-made card, caption and Unlock button. You post them from your own bot. The buyer pays in the dropp Mini App, Telegram confirms who they are, and you get back an order.paid that carries their Telegram id and your metadata.

Use it for PPV pushes in DMs, and for broadcasts in groups or channels where you want to know which member bought. If the buyer isn't on Telegram, share the normal checkout_url from POST /v1/links instead.

How Telegram selling works

1. Mint a vault link for an existing payment link with POST /v1/links/{id}/vault-link. You get a share URL and a telegram kit: card image, caption, button label and button URL.
2. Send the card from your bot: photo, caption and one inline button.
3. The fan taps Unlock. The dropp Mini App opens inside Telegram with the blurred cover and the price. Telegram signs the buyer's identity at this point, so you have nothing to pass along.
4. The fan pays inside the Mini App.
5. dropp delivers the content to the buyer's Telegram DM, and fires order.paid with buyer.telegram and the metadata of the copy they bought through.

Minting a vault link

POST /v1/links/{id}/vault-link (scope links:write) mints a new tracked copy of the link and returns everything you need to post it.

curl -X POST https://api.external.dropp.fans/v1/links/link_abc123/vault-link \
  -H "Authorization: Bearer drp_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: push-2026-07-29-vip-fr" \
  -d '{ "metadata": { "channel": "vip-fr", "chatter": "lea", "push": "2026-07-29" } }'

{
  "data": {
    "link_id": "link_abc123",
    "copy": {
      "id": "3f1c…",
      "slug": "aB3kPq9z",
      "metadata": { "channel": "vip-fr", "chatter": "lea", "push": "2026-07-29" }
    },
    "share_url": "https://app.dropp.fans/v/aB3kPq9z",
    "price": { "amount_cents": 1990, "currency_code": "EUR", "display": "€19.90" },
    "telegram": {
      "photo_url": "https://app.dropp.fans/v/aB3kPq9z/opengraph-image",
      "cover_url": "https://app.dropp.fans/v/aB3kPq9z/cover",
      "caption": "🔒 Bundle",
      "button": {
        "text": "🔒 Unlock for €19.90",
        "url": "https://t.me/…?startapp=…"
      }
    },
    "expires_at": "2027-07-29T10:00:00.000Z"
  }
}

The body is optional fields only; send {} when you have nothing to attach.

• Mint one vault link per push. Every call creates a new copy, and a copy's metadata comes back on every sale made through it. Minting per channel, chatter or send keeps attribution exact. With the same Idempotency-Key and body, a retry returns the original copy instead of a second one.
• The fee fields customer_fee_buyer_share_percent and partner_fee_buyer_share_percent are not accepted here and return 400.
• expires_at is one year after minting. Mint a fresh vault link for pushes after that.
• 404 means the link doesn't exist, is archived, isn't yours, or Telegram selling isn't enabled.
• Agency keys: pass profile_id in the query string, never in the body. See Acting for a creator.

Sending the Telegram card

telegram.photo_url is a ready-made 1200×630 card: the blurred cover, a lock and the price. Use telegram.cover_url, the blurred cover alone, if you want to compose your own artwork. Telegram's servers fetch both URLs directly.

Post the card with the Bot API's sendPhoto, and attach telegram.button as a URL button:

curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/sendPhoto" \
  -H "Content-Type: application/json" \
  -d '{
        "chat_id": 123456789,
        "photo": "https://app.dropp.fans/v/aB3kPq9z/opengraph-image",
        "caption": "🔒 Bundle",
        "reply_markup": {
          "inline_keyboard": [[
            { "text": "🔒 Unlock for €19.90", "url": "https://t.me/…?startapp=…" }
          ]]
        }
      }'

• button.url opens the Mini App checkout directly, so the buyer goes from the card to checkout in one tap. Use it as returned: it carries a signed token, and changing it breaks the checkout. Treat it as opaque, because it can also fall back to share_url.
• caption is 🔒 plus the link name. button.text is 🔒 Unlock for plus price.display. Both are suggestions, so you can write your own.
• The card and cover only ever show the blurred variant. The original media is not revealed before payment.

Bots, Telegram Business and userbots

Only a bot can attach inline buttons. A user-account session (a "userbot") can't send them, and Telegram drops the markup without an error.

No bot? Send the link. Posted as plain text, share_url renders its own preview in Telegram (blurred cover and price) and opens the Mini App when tapped. You lose the button, not the flow.

Identifying Telegram buyers

A Mini App checkout identifies the buyer from the data Telegram signs, so the identity comes from Telegram, not from what the buyer typed. It arrives on the order.paid webhook together with the copy's metadata:

{
  "event": "order.paid",
  "occurred_at": "2026-07-29T10:12:00.000Z",
  "object": "order",
  "data": {
    "id": "ord_abc123",
    "status": "paid",
    "type": "purchase",
    "amount": { "subtotal_cents": 1990, "total_cents": 1990, "currency_code": "EUR" },
    "seller": { "id": "pfl_creator", "username": "creator", "display_name": "Creator" },
    "buyer": {
      "email": "fan@example.com",
      "name": null,
      "country": null,
      "telegram": { "id": "991144", "username": "ada_l" }
    },
    "payment": null,
    "link": { "id": "link_abc123", "name": "Bundle" },
    "metadata": { "channel": "vip-fr", "chatter": "lea", "push": "2026-07-29" },
    "client_metadata": null
  }
}

• buyer.telegram.id is a string. Telegram ids can exceed 32 bits, and a string avoids precision loss in languages that parse JSON numbers as floats. Store it as a string or a 64-bit integer.
• buyer.telegram.username is null when the buyer has no username. Always key on id.
• buyer.telegram is null on orders that didn't go through Telegram.
• It is the same id your bot uses as chat_id, so you can follow up with the exact person who bought.
• The same buyer.telegram object appears on GET /v1/orders and on order.upsell_paid.
• order.paid can arrive more than once. Deduplicate on the event id, as described in Retries & Delivery.

Delivering the purchased content

When the creator's Telegram account is connected to dropp, dropp delivers the unlocked photos and videos to the buyer's own DM, sent from the creator's account with forwarding disabled. dropp posts into the creator's existing conversation with that buyer, or else messages their Telegram id directly. If delivery still fails after retries, dropp alerts the creator.

If the creator's Telegram account lives only in your tool and isn't connected to dropp, dropp can't post into their chats. Deliver it yourself when order.paid arrives:

1. Read buyer.telegram.id and link.id from the webhook.
2. For each content item in that link, call GET /v1/content/{id}/download-url (scope content:read). It returns signed URLs that expire after 15 minutes.
3. Send the files from your bot to that id.

// On order.paid, for a link you created with content_ids you stored
const { buyer, link } = event.data;
if (buyer?.telegram) {
  for (const contentId of contentIdsByLink[link.id]) {
    const res = await fetch(
      `https://api.external.dropp.fans/v1/content/${contentId}/download-url`,
      { headers: { Authorization: `Bearer ${process.env.DROPP_API_KEY}` } },
    );
    const { data } = await res.json();
    const method = data.type === "video" ? "sendVideo" : "sendPhoto";
    await fetch(`https://api.telegram.org/bot${process.env.BOT_TOKEN}/${method}`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        chat_id: buyer.telegram.id,
        [data.type === "video" ? "video" : "photo"]: data.download_url,
        protect_content: true,
      }),
    });
  }
}

• The API doesn't list which content ids a link contains: GET /v1/links/{id} returns only a count and the types. Keep the content_ids you passed to POST /v1/links.
• Ask for the signed URL right before sending, because it expires after 15 minutes.
• Telegram only fetches files by URL up to 5 MB for photos and 20 MB for other files. For larger videos, download the file and upload it to the Bot API as multipart/form-data.

Telegram selling limitations

• Only payment links can be sold in the Mini App. Donation pages and wishlists aren't supported there yet, so share their own checkout URLs.
• A vault link and its button stop working after expires_at, one year after minting.
• Inline buttons need a bot. Userbots can only send share_url as a plain link.
• Automatic delivery in the chat needs the creator's Telegram account to be connected to dropp. Otherwise you deliver the content yourself.

The embed SDK renders a dropp payment form, and optionally a funnel's upsell steps, directly on your own page. You design the page and place the fields; dropp's payment provider hosts the card input in its own frame, so card numbers never touch your code. Use it to sell a payment link (link_…) with your own layout, pass your own tracking data through to webhooks, and run one-click upsells after the first purchase.

For a boost, roses or payment-link checkout you can drop in with two lines and no custom form, use the Donation & Payment Widget instead. The two are separate scripts and can share a page.

Approve your domain first

The SDK only talks to dropp from domains the creator has approved. Add the exact origin of your page (for example https://yoursite.com) under Settings → Embedding in the dashboard. For the SDK, either an account-wide origin or one scoped to the link you sell works. A page on an unapproved domain gets 403 with EMBED_ORIGIN_NOT_ALLOWED when it opens the order, and no form appears. See Allowing your website for the details, which are the same for both scripts.

Loading the SDK

Load the script and stylesheet once per page. On site builders (Webflow, Framer, systeme.io), put them in the site's footer or custom-code slot, because builders don't run scripts pasted inside a content block.

<link rel="stylesheet" href="https://app.dropp.fans/embed/v1.css" />
<script src="https://app.dropp.fans/embed/v1.js" defer></script>

The script exposes window.Dropp with embed(), upsell.accept(), upsell.decline() and version.

Markup-only install

If you can't run your own script, paste the checkout markup and the SDK starts itself. It looks for .dropp-checkout[data-dropp-product] and expects the fields under these exact ids. Settings → Embedding → Get embed code generates this for you.

<div class="dropp-checkout" data-dropp-product="link_xxxxxxxxxxxxxxxxxxxxxx" data-dropp-locale="en">
  <input id="dropp-email" type="email" placeholder="you@example.com" />
  <select id="dropp-country" class="dropp-field" required>
    <option value="" disabled selected>Country</option>
    <option value="FR">France</option>
    <!-- … -->
  </select>
  <input id="dropp-card-holder" type="text" placeholder="Name on card" required />
  <div id="dropp-card" class="dropp-field"></div>
  <button id="dropp-pay" class="dropp-pay" type="button">Pay</button>
  <div id="dropp-upsell-target"></div>
</div>

• Only one checkout per page. If there are several containers, only the first is initialised.
• Containers added later (single-page apps, multi-step forms) are picked up automatically.
• Markup installs always run upsells in dropp-rendered mode inside #dropp-upsell-target.

Dropp.embed() options

For full control, call Dropp.embed() yourself once the page has the fields.

const handle = Dropp.embed({
  product: 'link_xxxxxxxxxxxxxxxxxxxxxx',
  fields: {
    card: '#dropp-card',
    email: '#dropp-email',
    country: '#dropp-country',
    cardHolderName: '#dropp-card-holder',
  },
  submitButton: '#dropp-pay',
  locale: 'en',
  upsell: { mode: 'dropp-rendered', target: '#dropp-upsell-target' },
  metadata: { click_id: 'gclid_xyz', user_ref: 'u_42' },
  onPaymentSuccess: ({ orderId, funnel, isTest }) => {},
  onPaymentError: ({ code, message }) => {},
  onComplete: (result) => {},
});

handle.isReady(); // true once the card form is mounted
handle.destroy(); // tear everything down

• The SDK waits up to 3 seconds for your selectors to appear, for builders that render late. After that, a missing element is reported through onPaymentError with code: "invalid_config", and in the console. embed() itself does not throw.
• fields.cardNumber, cardExpiry and cardCvv still work for old snippets but are deprecated: use the single card field.
• The creator's brand colour is applied to .dropp-checkout through the --dropp-accent and --dropp-focus CSS variables.

Payment errors

onPaymentError receives { code, message }. When you don't register it, the SDK shows a localized error banner at the top of .dropp-checkout instead.

Passing your own data (client_metadata)

Attach your own ids (user id, click id, campaign, A/B variant) to a checkout and get them back on the order's webhooks as client_metadata.

Dropp.embed({
  // …
  metadata: {
    click_id: new URLSearchParams(location.search).get('gclid') ?? '',
    user_ref: 'u_42',
  },
});

On a markup install, use the attribute instead:

<div class="dropp-checkout" data-dropp-product="link_xxxxxxxxxxxxxxxxxxxxxx"
     data-dropp-metadata='{"click_id": "gclid_xyz", "user_ref": "u_42"}'>

Limits: a flat map of string values only, max 20 keys, keys ≤ 64 characters, values ≤ 500 characters, ≤ 2048 bytes serialized. The server enforces the same limits. Don't confuse this with link-copy metadata: see the three metadata fields.

• Every upsell the buyer accepts afterwards inherits the order's client_metadata, including on separate upsell landing pages.
• Invalid metadata passed to Dropp.embed() stops the checkout from mounting (invalid_config). On a markup install, an attribute that is not valid JSON is ignored and the checkout still loads. Valid JSON with a non-string value ({"a": 42}) is rejected like the JS option, so the form does not mount.

Resolving metadata at pay-click

If the values come from a form the buyer fills after the checkout loads, pass a function. It is called when the buyer clicks pay, and the map it returns replaces the order's metadata just before the charge.

Dropp.embed({
  // …
  metadata: () => ({
    name: document.querySelector('#form-name').value,
    phone: document.querySelector('#form-phone').value,
  }),
});

• Return undefined or {} to keep the values already on the order.
• A resolver that throws or returns an invalid map, or an update that fails on the network, is skipped: the payment still goes through with the previous metadata. Turn on debug logging to see why.

Funnels and upsells in the embed SDK

When the link has an upsell funnel, the SDK takes over after the first payment. What happens depends on the funnel's render mode (set in the funnel editor) and on your upsell option.

Every step charges the card saved during the first payment. The buyer never re-enters it.

Rendered mode

Dropp.embed({
  // …
  upsell: {
    mode: 'dropp-rendered',
    target: '#dropp-upsell-target',
    // Optional: called when the buyer accepts a step.
    stepMetadata: (step) => ({ ab_variant: 'b', position: String(step.position) }),
  },
});

stepMetadata returns a map with the same limits as client_metadata. It is stored on that upsell and sent only on its order.upsell_paid webhook as step_metadata. A resolver that throws or returns an invalid map is skipped and never blocks the charge.

Headless mode

Render the offer yourself from onStepChange, then report the buyer's choice:

Dropp.embed({
  // …
  upsell: { mode: 'headless' },
  onStepChange: (step) => {
    if (!step) return; // funnel finished
    renderOffer(step); // step.offer.price, step.offer.name, step.copy.acceptCta…
  },
});

const r = await Dropp.upsell.accept(step.id, {
  metadata: { variant: 'exit-popup' }, // optional, sent as step_metadata
});
// or: const { nextStep } = await Dropp.upsell.decline(step.id);

• step.offer.price is in major units (4.99), unlike amountCents on the result below.
• By default the SDK shows its own confirmation overlay (card brand, last 4 digits, amount) before charging. confirmation: 'manual' skips it; you must then show your own confirmation before calling accept().
• accept() and decline() only work on the current step, and one call at a time: a second call while one is running throws UPSELL_IN_FLIGHT.
• Invalid metadata on accept() throws before anything is charged.

Upsell results

Dropp.upsell.accept() resolves with:

onUpsellPaymentFailed({ stepId, isDownsell, reason, retryable, message }) fires once per failed attempt, in both rendered and headless modes, just before accept() resolves. reason is authentication_failed, declined or error. message is provider text for your logs: don't show it to the buyer.

onComplete receives the run's summary: totalCharged (cents, first payment plus accepted upsells), currency, accepted and declined (step ids), parentOrderId and isTest.

Upsell landing pages (external pages mode)

In this mode each step is a page you build. After the first payment the SDK sets a dropp_session cookie on your domain (30 minutes) and redirects to step 1. Load the SDK on every step page and add the step's buttons:

<div class="dropp-upsell" data-dropp-step="1" data-dropp-metadata='{"page_variant": "b"}'>
  <button class="dropp-upsell-accept" type="button">Yes, add it</button>
  <button class="dropp-upsell-decline" type="button">No thanks</button>
</div>

• data-dropp-step is the 1-based step position. Add data-dropp-variant="downsell" on a downsell page. The dashboard generates these snippets for each step.
• data-dropp-metadata is optional and becomes that step's step_metadata.
• Tracking parameters on the checkout URL (utm_*, click ids…) are carried onto every step and the thank-you page.
• Buyers who block cookies get the session in the URL (?dropp_session=) and see a short notice.
• Each decision fires a dropp:upsell-step-decided event on window with stepId, stepPosition, accepted, isDownsell, amountCents and currency, for your analytics.

3-D Secure on upsells

A creator can require bank verification on every upsell and downsell of a funnel: Funnel → Settings → Require bank verification (3-D Secure). It is off by default. Your integration does not change either way: the SDK reads the setting and runs the flow.

• On accept, the SDK runs the bank's device check in a hidden frame (up to 10 seconds), then places a hold on the card instead of charging it.
• If the bank asks the buyer to verify, the SDK shows the bank's page in its own overlay, in every mode, including headless. You cannot render it yourself. In headless mode the accept() promise stays pending until the buyer finishes.
• The hold is captured only when the bank authenticated the buyer. In every other case the hold is released, nothing is charged, and the buyer stays on the same offer: authentication_failed, retryable: true. Rendered mode shows a Retry button; landing pages re-enable the accept button with an inline notice.
• A failed or abandoned verification sends no webhook.

The trade-off: verification moves chargeback liability to the bank, but some buyers abandon at the bank's step. Try it on one funnel first.

Testing the embed SDK

A funnel with Test mode on (in the funnel's settings) charges against the payment provider's test environment: test cards work and no money moves.

• The checkout shows a TEST MODE — no real charges banner.
• onPaymentSuccess and onComplete carry isTest: true. Filter these out of your own conversion tracking (pixels, analytics).
• Test orders send order.paid / order.upsell_paid only to webhook endpoints registered with a test key, with livemode: false; your live endpoints never receive them. To check a webhook handler on a test run, register an endpoint with a test key.
• To test 3-D Secure on upsells, price the test offer above 100.00. The test environment only authenticates amounts above 100.00; at 100.00 or below every attempt ends in authentication_failed. This rule applies to the test environment only.

Getting results on webhooks

The browser callbacks are for your page's UI. To grant access, fulfil or record a sale, use webhooks: they are signed and can't be faked from a browser.

• order.upsell_paid is a separate event type: subscribe your endpoint to it, or upsell sales won't reach you. step_metadata never appears on order.paid.
• Join the two with parent_order.id. Don't assume order.paid always arrives before a fast order.upsell_paid.
• The orderId from onPaymentSuccess is the data.id of order.paid.

Debugging the embed SDK

The SDK is quiet by default: only errors reach the console. Turn on a timestamped timeline of every step (order opened, card form loaded, pay clicked, funnel state, 3-D Secure, redirects) in any of these ways:

• open the page with ?dropp_debug=1: the flag is kept in localStorage so it follows the buyer through the funnel's redirects;
• run localStorage.dropp_debug = '1' in the console and reload;
• set window.DROPP_DEBUG = true before the SDK script;
• pass debug: true to Dropp.embed().

Turn it off with localStorage.removeItem('dropp_debug'). Every line starts with [dropp].

If your page sends a Content-Security-Policy, it must allow the SDK's script and stylesheet from https://app.dropp.fans, the card form from https://cdn.safecharge.com, requests to dropp's payment API, and frames from the payment provider and the buyer's bank. Run a checkout with debug logging on and look for blocked requests in the console.

The widget puts a dropp boost, roses or payment link checkout on your own website with two lines of HTML. The fan pays without leaving your page. The checkout is a dropp-hosted page inside an <iframe>, so card data never touches your site. The widget sizes itself, uses the creator's brand colour, and tells your page when a payment lands.

Widget or embed SDK?

They are separate scripts (/widget/v1.js and /embed/v1.js) with separate globals (DroppWidget and Dropp), and you can use both on one page.

Allowing your website

A dropp widget only loads inside websites the creator has approved. Browsers enforce this: the widget page is served with a Content-Security-Policy: frame-ancestors header listing the approved origins, so an unapproved site is refused by the browser itself.

1. In the dashboard, open Settings → Embedding (direct link: /dashboard/creator/<profile-id>/settings?tab=embedding). Agency admins find the same tab in a managed creator's settings.
2. Click Add origin and enter the exact origin of your site, for example https://yoursite.com: scheme and host only, no path. https:// is required (http://localhost is allowed for development).
3. Leave Scope on All links (account-wide) and click Add.

Add one origin per site. https://yoursite.com and https://www.yoursite.com are two different origins. After adding one, allow up to a minute before the widget loads there.

The Pending review / Verified status on a row does not affect widgets.

Adding the widget

Paste the loader once per page, ideally just before </body>, and a container wherever the checkout should appear. Settings → Embedding → Widgets generates both for each of your links.

<div data-dropp-donation="don_lk_xxxxxxxxxxxxxxxxxx"></div>
<script src="https://app.dropp.fans/widget/v1.js" defer></script>

• One container carries exactly one of the three attributes.
• Several widgets can share a page, for example a boost button next to a product. Each works on its own.
• Containers added to the page later (single-page apps, lazy blocks) are mounted automatically. A container removed from the page is cleaned up.
• On site builders (Webflow, Framer, systeme.io), put the <div> in an Embed / Raw HTML block and the loader in the site's footer code area. Builders don't run scripts pasted inside a content block.

Widget options

All optional, set on the container.

You don't need to set a height for normal use. The widget reports its content height as the fan moves through the form, so there is no inner scrollbar. Don't give the container a fixed height or overflow: hidden.

Boosts, roses and payment links

Boosts and roses (don_lk_…) let the fan choose the amount. Boost and roses orders are never test orders.

Payment links (link_…) sell the link at its price. The widget never sends an amount: the price is read from the link on dropp's side, so nothing on your page can change what the fan pays.

• After paying, the fan sees a confirmation with an Open my purchase button. It opens their order page (downloads, and the link's upsell offers if it has a funnel) in a new tab. The widget itself never navigates your page.
• Upsell steps don't run inside the widget. If the link has a funnel, the form shows the card-on-file consent line, because the order page runs those offers. To run upsells on your own page, use the embed SDK.
• Links with an auction or a raffle attached can't be embedded: the browser refuses the frame and the widget shows its unavailable notice.
• A link whose funnel is in test mode produces test orders (isTest: true), which send no webhooks.

Selling through a tracked copy

If you mint link copies through the API, one per fan or campaign, embed the parent id and pass the copy's slug as the ref:

<div data-dropp-link="link_xxxxxxxxxxxxxxxxxxxxxx" data-dropp-ref="my-copy-slug"></div>
<script src="https://app.dropp.fans/widget/v1.js" defer></script>

• The sale is attributed exactly as if the fan had opened the copy's own URL: order.paid carries the copy's metadata, and the copy's fee settings apply. It works for all three kinds. For donation copies, a per-copy minimum amount also applies.
• The slug is the last part of the copy's URL (app.dropp.fans/s/<slug>): letters, digits, _ and -, up to 64 characters. Any other value (a copy id, a full URL) is dropped: the sale still completes, but without attribution. Check the webhook of your first test sale.
• The ref must belong to a copy of the link you embed.
• Approved origins are per account or per link, never per copy: every copy is covered by the origin you already added.
• The browser event never carries the ref. Learn which copy sold from the order.paid webhook, and join it to the browser event on orderId if you need both.

The dropp:widget:complete event

When a payment succeeds, the widget dispatches dropp:widget:complete on its container. It bubbles, so one listener on document sees every widget on the page.

document.addEventListener('dropp:widget:complete', (e) => {
  const { orderId, amountCents, currency, isTest, kind, product } = e.detail;
  showThankYou(orderId);
});

kind and product come from your own snippet, not from the checkout. The event never contains the buyer's email or any other buyer data.

Mounting the widget from JavaScript

The loader mounts every matching container on its own. To control mounting yourself, call DroppWidget.mount():

const widget = DroppWidget.mount({
  kind: 'donation',                  // 'donation' | 'flower' | 'link'
  product: 'don_lk_xxxxxxxxxxxxxxxxxx', // a link_… id with kind: 'link'
  target: '#my-slot',                // selector or element
  locale: 'fr',
  initialHeight: 500,
  layout: 'form',                    // kind: 'link' only
  ref: 'my-copy-slug',               // optional tracked-copy slug
  onComplete: (result) => console.log(result), // same fields as the event
  onUnavailable: () => showFallback(), // blocked, not found or offline
});

widget.isReady(); // true once the checkout answered
widget.destroy(); // removes the frame and stops listening

The event is still dispatched when you pass onComplete. DroppWidget.completeEvent holds the event name and DroppWidget.version the bundle version.

Content Security Policy for the host page

If your page sends its own Content-Security-Policy, allow the loader script and the widget frame:

script-src https://app.dropp.fans;
frame-src https://app.dropp.fans;

• Merge these into your existing directives rather than replacing them. If you set child-src and no frame-src, add https://app.dropp.fans there.
• The widget needs no 'unsafe-inline' for styles: it only sets styles through script properties, which a strict style-src allows.
• If you send a Permissions-Policy header, don't disable payment for https://app.dropp.fans, or the Apple Pay button won't appear in the frame.
• The card form, and a bank's 3-D Secure page, load inside the dropp frame, so your policy doesn't need to list the payment provider or banks.

Bank verification (3-D Secure). When a bank challenges a payment, the widget temporarily covers the whole viewport so the fan can complete it, then returns to its size. Don't place the widget inside an element with a CSS transform, filter, perspective, backdrop-filter or contain: paint: those trap the full-screen overlay inside the box. The loader logs a console error when it finds one.

Troubleshooting the widget

Open your browser console on your own page first. Most problems are named there. Warnings about data-dropp-locale, data-dropp-layout and data-dropp-ref only show with debug logging on: open the page with ?dropp_debug=1.

Start every integration with two calls: GET /v1/me to learn who your credential acts as, and GET /v1/creators to list the creators you can act for.

Who am I acting as? (GET /v1/me)

GET /v1/me requires no scope — any valid credential may introspect itself. The field you want is effective_profile_id, not profile.id. For a solo creator they happen to be equal, which is why reading the wrong one only breaks later.

{
  "data": {
    "key": null,
    "app": { "id": "papp_…", "name": "Your App", "slug": "your-app", "scopes": ["links:read"], "multi_creator": false },
    "profile": { "id": "pfl_…", "username": "marie", "display_name": "Marie Dupont" },
    "agency": null,
    "acts_as": { "id": "pfl_…", "username": "marie", "display_name": "Marie Dupont" },
    "effective_profile_id": "pfl_…",
    "connected_creators": [
      {
        "id": "pfl_…",
        "username": "marie",
        "display_name": "Marie Dupont",
        "grant_id": "…",
        "status": "active",
        "scopes": ["links:read"],
        "scopes_stale": false,
        "granted_via_agency": null
      }
    ]
  }
}

On each connected_creators row, filter on status === "active" to know what you can call, and read granted_via_agency (null when the creator connected you themselves, { id, name } when an agency admin delegated them) to know where it came from. scopes_stale: true means the grant predates scopes your app gained later — the creator must reconnect.

Who can I call? The four cases

On a single-creator app, a delegated grant is recorded but stays pending until your app is switched to multi-creator — ask us for the switch, or have the creator connect themselves.

Which creators can I act for? (GET /v1/creators)

No scope required. Use it to build a creator picker, and use each id as the profile_id on writes. What you get back depends on the key:

Don't infer creators from the links endpoint. A creator who hasn't published anything owns no links, so a brand-new agency would appear to have no creators at all. This endpoint is independent of content: creators appear from day one.

display_name is always populated (falling back name → username → placeholder), so it is safe to render directly. Most creators have no username, so never build a label from username alone.

Creating creator accounts — two endpoints, two callers

Both create a real person's account and email them an invite. Pick by who you are:

Onboarding onto your agency

Links, donation pages and wishlists can only be owned by a creator profile — your agency's own profile can never own one. POST /v1/agency/creators creates that creator, usable immediately: it appears in GET /v1/creators and can own content before the person has ever logged in. They receive an email inviting them to take the account over.

• Agency keys only. The creator is always created in the key's own agency. Creator-bound keys and OAuth apps get 403 unsupported_credential, and the key's owner must be an ADMIN or MANAGER of the agency.
• Keys minted before this scope existed don't carry it. Create a new key with creators:write ticked.
• The revenue split starts at 100% agency / 0% creator, exactly like a dashboard invite. Agencies change it in the dashboard — there is no split API.
• 409 email_unavailable is terminal for that address, most often because it already has a dropp account. Invite them from the dashboard instead. Don't iterate over address variants: rejections carry their own tight budget.
• Retries are safe. The same address twice returns the same creator with "status": "existing" and sends no second invite.
• Budgets are per agency: 30/hour and 200/day (see Rate Limits).

Provisioning a referred seller

For approved affiliate partners, not for agencies onboarding their own talent — the referral guide covers it end to end. POST /v1/creators authenticates your app, not a user: send X-Dropp-App-Key and no Authorization header — there is no creator behind the call yet. It requires a referral code bound to your app; the code is taken from that binding, never from the request.

• Affiliate model, not agency membership. The account is an independent seller with your referral attribution attached at signup. No agency membership and no revenue split are created.
• type: "AGENCY" (with agency_name) creates an agency account instead, with the invited person as its ADMIN.
• Idempotent on email. An address that already has a dropp account is returned untouched with status: "already_exists" and is never re-attributed.
• The person takes ownership themselves by email and cannot sell until KYC is complete.

Acting for the creators you provisioned

Provisioning also creates an install: a grant that lets your app act as that creator with the same X-Dropp-App-Key and no Bearer token. Name the creator with profile_id and call any endpoint your app's scopes allow:

curl "https://api.external.dropp.fans/v1/links?profile_id=prof_new123" \
  -H "X-Dropp-App-Key: drp_app_live_..."

• Only creators your app provisioned. A creator who connected through Login with dropp is reached with their OAuth token, and an address that returned status: "already_exists" gets no install.
• Name the creator on every call — profile_id in the body for writes, in the query for reads. An unnamed request is 400 ambiguous_scope.
• The creator can revoke you from Settings → Connected Apps; every later call returns 403 profile_not_connected.
• Scopes are the intersection of your app registration and the install.

Links are built from content you upload first. You never send file bytes through the API: you ask for a one-time upload URL, send the file straight to our media provider, then use the returned content_id in POST /v1/links. Content is stored privately. To read it back, you ask for short-lived signed URLs.

Requesting an upload URL

POST /v1/content/upload-url (scope content:write) creates the content record and returns where to send the bytes.

curl -X POST https://api.external.dropp.fans/v1/content/upload-url \
  -H "Authorization: Bearer drp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "image", "content_type": "image/jpeg", "filename": "set-01.jpg", "profile_id": "pfl_creator" }'

{
  "data": {
    "content_id": "ctt_abc123",
    "type": "video",
    "upload_url": "https://upload.videodelivery.net/…",
    "upload_protocol": "basic",
    "uid": "a1b2c3d4e5f6",
    "upload_budget": {
      "per_hour": { "limit": 100, "remaining": 99, "reset_in_seconds": 3540 },
      "per_week": { "limit": 500, "remaining": 480, "reset_in_seconds": 518000 }
    }
  }
}

• upload_protocol tells you how to send the file: basic or tus.
• uid and upload_budget are returned for videos only. upload_budget shows what is left after this upload.
• upload_url is single-use and expires quickly, so request it right before you upload.

Basic uploads

Without size_bytes, you get a basic URL. Send the whole file in one multipart POST with a file field. Images always use this protocol.

curl -X POST "$UPLOAD_URL" -F "file=@set-01.jpg"

Basic video uploads are capped at 200 MB. Sending tus PATCH requests to a basic URL fails.

Resumable video uploads (tus)

For videos over 200 MB, or whenever you want to upload in chunks and resume after a network failure, pass the exact file size as size_bytes. The response then returns "upload_protocol": "tus", and upload_url points to a tus upload that already exists.

curl -X POST https://api.external.dropp.fans/v1/content/upload-url \
  -H "Authorization: Bearer drp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "type": "video", "content_type": "video/mp4", "size_bytes": 524288000 }'

Because the upload is already created, give the URL to your tus client as the upload URL, not as the creation endpoint:

import * as tus from "tus-js-client";

const upload = new tus.Upload(file, {
  uploadUrl: data.upload_url, // not `endpoint`
  chunkSize: 50 * 1024 * 1024, // a multiple of 256 KiB
  retryDelays: [0, 3000, 10000, 30000],
  onError: (err) => console.error("upload failed", err),
  onSuccess: () => console.log("uploaded", data.content_id),
});
upload.start();

• size_bytes must match the real file size. The tus upload is created with that length.
• Videos can be up to 1 hour long, with either protocol.

Waiting for video processing

Images are usable as soon as the upload finishes. Videos transcode asynchronously. Poll GET /v1/content/{id} (scope content:read) every few seconds until status is ready, and only then attach the video to a link.

curl https://api.external.dropp.fans/v1/content/ctt_abc123 \
  -H "Authorization: Bearer drp_live_..."

{ "data": { "id": "ctt_abc123", "type": "video", "status": "processing", "created_at": "2026-06-13T10:30:00.000Z" } }

• A video is processing until it has a playback id, then ready.
• Images, and legacy audio and pdf items, always read ready. An image is ready as soon as its upload URL is issued: dropp can't tell whether you actually sent the bytes. Only use the content_id of an image whose upload succeeded.

The content object

GET /v1/content and GET /v1/content/folders/{id} return full content objects. GET /v1/content/{id} returns only id, type, status and created_at.

{
  "id": "ctt_abc123",
  "name": "promo.mp4",
  "type": "video",
  "status": "ready",
  "created_at": "2026-06-20T10:00:00.000Z",
  "is_archived": false,
  "media": {
    "cf_uri": null,
    "stream_uid": "a1b2c3d4",
    "playback_id": "pbk_abc123",
    "duration": 45.5,
    "width": 1920,
    "height": 1080,
    "thumbnail_url": "https://…/thumbnail.jpg",
    "content_type": "video/mp4"
  }
}

The media references are identifiers, not playable URLs: content is stored privately, so you can't embed a video with stream_uid or playback_id alone. Use the signed URLs below.

Playing and downloading content

GET /v1/content/{id}/download-url (scope content:read) returns signed URLs for content you own. They are valid for 15 minutes, so request a fresh set each time instead of storing them.

curl https://api.external.dropp.fans/v1/content/ctt_abc123/download-url \
  -H "Authorization: Bearer drp_live_..."

{
  "data": {
    "content_id": "ctt_abc123",
    "type": "video",
    "playback_url": "https://videodelivery.net/<token>/manifest/video.m3u8",
    "download_url": "https://videodelivery.net/<token>/downloads/default.mp4",
    "expires_at": "2026-06-24T10:15:00.000Z"
  }
}

• Video: playback_url is a signed HLS manifest. Give it to any HLS player to stream or embed the video. download_url is the MP4. The first time you download a video, the MP4 can take a short moment to become available.
• Image: playback_url is null, and download_url is a signed image URL.
• 409 means the video is still processing. 400 means the type can't be downloaded (audio, pdf). 404 means the content doesn't exist or isn't yours.

Retrying uploads and creates safely

POST /v1/content/upload-url does not support Idempotency-Key. Each call creates a new content record and, for videos, uses budget. If a request times out, check GET /v1/content before you ask again.

The create calls that come next — POST /v1/links, POST /v1/links/{id}/copies and POST /v1/links/{id}/vault-link — do accept an Idempotency-Key header. Send a unique value, up to 255 characters, for each logical create:

• Keys are scoped to your credential, so two API keys can use the same value independently.
• Bodies are compared by content: key order and whitespace don't matter.
• A request still in progress after 10 minutes is treated as abandoned, and the next retry with that key runs again.

Payment links sell uploaded content at a fixed price. Every link is shared through copies: each copy has its own slug, checkout_url and optional metadata, so you can track which fan, conversation or campaign each sale came from.

Live and test links — a link carries livemode, set from the key that created it and never changed. A link created with a test key checks out on the payment provider's sandbox and is only ever visible to test keys.

Link folders — creators organize links into folders in the app. Agencies can list folders and sync only the ones they select: filter links to a folder with GET /v1/links?folder_id=link_clt_....

Tracking fans & attribution (metadata)

Attach an opaque JSON metadata object to a link copy, and dropp echoes it back when a fan opens the link and when they buy.

• Metadata lives on a link copy — the value identified by the slug — not on the URL itself. Adding your own query params to a share URL is not captured.
• Set it when you mint a copy with POST /v1/links (creates a link and its first copy) or POST /v1/links/{id}/copies (mints another copy of an existing link).
• Share the returned checkout_url. You then receive the exact same metadata on the link_copy.opened and order.paid webhooks and on GET /v1/orders.
• Copies made with the dropp app's "copy link" button carry no metadata, so their orders arrive with metadata: null.
• Limits: JSON object only (not array or null), max 8 KB, 5 levels deep, 100 keys, keys ≤ 128 characters, string values ≤ 2048 characters.

Two other metadata fields exist — don't conflate them with link-copy metadata:

• client_metadata — set by embed-SDK integrations when initializing a checkout. A flat string-to-string map: max 20 keys, keys ≤ 64 characters, values ≤ 500 characters, ≤ 2048 bytes serialized. Echoed on order.paid and order.upsell_paid.
• step_metadata — attached to a funnel step; echoed only on order.upsell_paid. Same limits as client_metadata.

Crediting a team member (operator_profile_id)

metadata is yours and opaque — dropp never reads it. To make a sale also count for a specific team member (a chatter) in dropp's own agency stats, name them with operator_profile_id on any copy-minting call: POST /v1/links, POST /v1/links/{id}/copies, POST /v1/donation-links/{id}/copies and POST /v1/wishlists/{id}/copies.

curl -X POST https://api.external.dropp.fans/v1/links/link_abc123/copies \
  -H "Authorization: Bearer drp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "operator_profile_id": "aa0e8b91-…", "metadata": { "push": "vip-fr" } }'

• The id must be an ADMIN or MANAGER of an agency the creator belongs to. Anything else is rejected with 400 operator_not_in_scope rather than silently falling back.
• Omit the field and the copy is credited to the creator.

Who pays dropp's fee, per copy

Every copy-minting call accepts two optional fields that decide who bears dropp's fees on sales through that copy. They are not metadata: "fee": "split" inside metadata is echoed back and never reaches the checkout.

• Per copy only. The link and every other copy are unchanged. Omit both fields and the seller's account setting, or their agency's fee deal, decides.
• An explicit value also applies inside an agency fee deal. Under such a deal the partner fee is already 0, so partner_fee_buyer_share_percent has no effect there.
• Upsells follow the copy. A fan who bought through a copy with an explicit value gets the same rule on that funnel's upsells.
• Not accepted on POST /v1/links/{id}/vault-link.

Every copy the API mints comes back with a fees block: what you stored, and under effective, what the next checkout will actually use, with *_decided_by naming what decided it (copy, seller_default, agency_fee_deal, campaign or funnel). effective is null when the seller's fee context could not be read at mint time.

Donation pages (tips, "boosts") that fans pay through. Sharing and attribution work exactly like payment links: every donation page has tracked copies, each with its own slug, checkout_url and metadata, echoed back on order.paid ("type": "donation") and GET /v1/orders. All amounts are integer cents.

Every donation page carries livemode, set from the key that created it. Scopes: donation_links:read for reads, donation_links:write for create, copy and deactivate. Keys minted before these scopes existed don't carry them — create a new key with them ticked.

One donation page per creator (and per mode)

A creator has one donation page, whether it was created in the dropp app or through the API. A second POST /v1/donation-links for the same creator returns 409 donation_link_exists, with the existing page in error.details.donation_link_id when your key can read it. Don't create a second page to vary the terms: mint a copy of the existing one.

{
  "error": {
    "code": "donation_link_exists",
    "message": "This creator already has a donation page (don_lk_abc123). Only one is allowed per creator: mint tracked copies of it with POST /v1/donation-links/don_lk_abc123/copies.",
    "status": 409,
    "request_id": null,
    "details": { "donation_link_id": "don_lk_abc123", "is_active": true }
  }
}

details.is_active tells you what to do next. true: mint copies of that page. false: the page was deactivated (DELETE deactivates, it does not free the slot) and cannot take payments, so don't mint copies of it — their checkout would be refused. Reactivation is not available through the API yet; the creator can do it in the dropp app. When the existing page is outside your key's scope, the 409 carries no details.

A test key gets its own slot: a creator can have one live donation page and one test donation page at the same time, and each key only ever sees its own.

Per-copy minimum (min_amount_cents)

POST /v1/donation-links/{id}/copies accepts an optional min_amount_cents: the minimum a fan must give when checking out through that copy. It replaces the page minimum for that copy only, and may be lower or higher than it. Omit it to inherit the page minimum.

curl -X POST https://api.external.dropp.fans/v1/donation-links/don_lk_abc123/copies \
  -H "Authorization: Bearer drp_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "min_amount_cents": 20000, "metadata": { "fan": "tg_123" } }'

The response always carries the effective minimum as copy.min_amount_cents. It returns 400 when the value is below 100 or above the page's max_cents. The minimum belongs to the copy URL: a fan who opens the bare page gets the page minimum.

DELETE /v1/donation-links/{id} is a soft delete: the page stops accepting donations. It is idempotent; there is no hard delete, because orders reference the page. Every write endpoint accepts an Idempotency-Key.

Wishlists are shared and tracked the same way as links — plus items. Fans contribute toward each item; wishlist purchases arrive as orders with "type": "wishlist".

Scopes: wishlists:read for reads, wishlists:write for create, items, copy and archive. Older keys don't carry these scopes — create a new key with them ticked.

• Creating. name is the only required field; send up to 50 items, created in the order you send them. The response includes the wishlist, its items and a first tracked copy. profile_id defaults to the key owner; agency keys may name their creators.
• Items. funded_amount_cents is how much fans have contributed so far; is_funded flips when the target is reached. Items inherit the wishlist's currency. Item URLs (amazon_url, image_url) must include the protocol.
• Copies. POST /v1/wishlists/{id}/copies takes the same body as the donation-link copy endpoint (metadata, operator_profile_id and the per-copy fee fields). An archived wishlist returns 404.
• Archiving. DELETE /v1/wishlists/{id} is a soft delete: the wishlist stops accepting contributions. It is idempotent.

Every write endpoint accepts an Idempotency-Key.

Orders are what fans paid for. Each order carries the metadata of the link copy it was bought through (see Tracking fans & attribution), or null if none.

The status filter takes the uppercase value (?status=PAID), while the status field in the response is lowercase (paid).

Every order carries livemode. A live key lists only real orders (livemode: true); a test key lists only sandbox orders paid with a test card (livemode: false). The two never mix, and an order id from one mode is a 404 on a key of the other.

amount.subtotal_cents is the listed price and amount.total_cents is what the buyer paid, which differ when the buyer bears part of dropp's fee.

Transactions are revenue records: who received money, and from which order. seller is the creator who made the sale — distinct from recipient, who received the money. id is trx_… on current rows and inc_… on rows from before September 2025; both come from the same endpoint.

The type filter takes the uppercase enum — REVENUE, AGENCY_REFERRER, CREATOR_REFERRER. Anything else is a 400. The type field in the response is lowercase, and can also be income on a recent row that has no revenue type yet. Every row carries livemode: a live key only ever returns livemode: true rows, and a test key only livemode: false ones — sandbox charges never appear on a live key.

Creators inside an agency

Where a creator's earnings land depends on their revenue split. When the agency takes the cut, the earning is recorded against the agency, not the creator — so a creator-scoped call returns nothing for them even though they are selling. On dropp today that is most earnings, not an edge case.

If an agency admin connected that creator to your app, your token also reads what that agency earned from that creator's sales. Keep naming one creator per request:

curl "https://api.external.dropp.fans/v1/transactions?profile_id=pfl_creator" \
  -H "Authorization: Bearer <access_token>"

Read the rows, don't assume them:

• recipient says who holds the money — { "type": "agency" } on these rows, { "type": "creator" } when the split pays the creator directly. A creator-facing UI should not present an agency-held amount as the creator's own balance.
• seller ties the row back to the profile_id you asked for on REVENUE rows. On the referral types it does not: there the creator you asked for is the referrer, and seller is whoever they referred.
• Filter with ?type=REVENUE for sale proceeds only; agency referral commissions also appear here.

Webhooks send real-time HTTP callbacks to your server when events happen on your dropp account: a paid order, an opened link, a tracked copy being viewed. Every delivery is a signed POST — see Security.

Managing endpoints

Register endpoints with your API key (webhooks:write; webhooks:read for the reads), or from Settings → API → Webhook Endpoints in the dashboard.

• Max 5 endpoints per account. Each subscribes to 1–10 event types.
• URLs must be HTTPS and resolve to a public IP.
• The signing secret is returned only once, on create and on rotate. Rotation is an instant cutover — there is no overlap window with the old secret.
• A failed delivery can be redelivered with POST /v1/webhooks/deliveries/{id}/retry (5 per minute).

App feed — one endpoint for every connected creator

If your app serves many creators, don't register an endpoint per creator (that is one signing secret each). Register a single app feed with your app key and no Bearer:

curl -X POST https://api.external.dropp.fans/v1/app/webhooks/endpoints \
  -H "X-Dropp-App-Key: drp_app_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://yourapp.example/dropp/events", "events": ["order.paid"] }'

The feed carries the subscribed events for every creator your app holds an active connection for — provisioned or OAuth-connected. Each delivery's envelope carries profile_id, so route on that.

• Revocation is immediate. The connection is re-checked on every event: a creator who disconnects your app stops appearing on the feed at once.
• A creator's own endpoints still fire. If a creator also registered their own webhook, both receive the event with the same X-Dropp-Event-Id — deduplicate on it.
• Delivery budget for a feed is 300/min (vs 30/min for a single creator's endpoint). Excess is delayed, never dropped.
• Signature verification, retry schedule and circuit breaker are identical to a normal endpoint.