API reference

Set the creator’s subscription tier

Creates or replaces the creator's subscription tier. This is a full replace: fields you leave out go back to their defaults (`trialDays` 0, no description or pitch, active).

View as MarkdownUpdated Oct 26, 2026

PUT/api/external/subscriptionNew

Creates or replaces the creator's subscription tier. This is a full replace: fields you leave out go back to their defaults (trialDays 0, no description or pitch, active).

Same rules as the dashboard: priceUsd is USD dollars, either 0 (free) or between $5 and $750. isActive: false pauses new sign-ups. Existing subscribers keep the price they signed up at.

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 canEditProfile). See Agencies.

Request body

Content type: application/json

Name	Type	Required	Description
`priceUsd`	number	Required	USD dollars per interval. 0 = free; otherwise $5–$750. Rounded to cents. Min: 0 Max: 750
`interval`	string	Required	Billing interval. One of: `monthly`, `weekly`
`trialDays`	integer	Optional	Free trial length in days. Default: `0` Min: 0 Max: 30
`description`	string	Optional	What subscribers get (cut at 500 characters). Max length: 500
`pitchMessage`	string	Optional	Short pitch shown in the subscribe sheet (cut at 500 characters). Max length: 500
`isActive`	boolean	Optional	false pauses new sign-ups. Default: `true`

$9.99 a month

{
  "priceUsd": 9.99,
  "interval": "monthly",
  "description": "All my sets, first."
}

Responses

200The saved tier.

Name Type Description

tier

SubscriptionTier

The tier now in effect.

Show child attributes

`priceUsd`	number	USD dollars per interval. 0 = free subscription.
`currency`	string	Always "USD". One of: `USD`
`interval`	string	Billing interval. One of: `monthly`, `weekly`
`trialDays`	integer	Free trial length in days (0 = none).
`description`	string \| null	What subscribers get.
`pitchMessage`	string \| null	Short pitch shown in the subscribe sheet.
`isActive`	boolean	False = paused: no new sign-ups. Existing subscribers are unaffected.

Example response

{
  "tier": {
    "priceUsd": 9.99,
    "currency": "USD",
    "interval": "monthly",
    "trialDays": 0,
    "description": "All my sets, first.",
    "pitchMessage": null,
    "isActive": true
  }
}

Errors

Status	Body	When
400	`{"error":"priceUsd must be 0 (free) or at least 5"}`	`priceUsd` missing, not a number or negative.
400	`{"error":"The minimum price is $5. Set the price to free or at least $5."}`	Priced above 0 but below $5.
400	`{"error":"The maximum price on Dropfans is $750. To request an increase, contact [email protected]."}`	Priced above $750.
400	`{"error":"interval must be 'monthly' or 'weekly'"}`	Missing or unknown interval.
400	`{"error":"trialDays must be a whole number from 0 to 30"}`	Bad trial length.
400	`{"error":"isActive must be true or false"}`	`isActive` is not a boolean.
400	`{"error":"Invalid JSON body"}`	The body is not valid JSON.
401	`{"error":"Unauthorized","code":"unauthorized"}`	Missing or invalid API key.
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":"canEditProfile"}`	With `X-Dropfans-Account`: the agency lacks `canEditProfile` 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 PUT "https://www.dropfans.io/api/external/subscription" \
  -H "Authorization: Bearer $DROPFANS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "priceUsd": 9.99,
  "interval": "monthly",
  "description": "All my sets, first."
}'

const res = await fetch(`https://www.dropfans.io/api/external/subscription`, {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "priceUsd": 9.99,
    "interval": "monthly",
    "description": "All my sets, first."
  }),
});
console.log(await res.json());

import os
import requests

res = requests.put(
    "https://www.dropfans.io/api/external/subscription",
    headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
    json={
        "priceUsd": 9.99,
        "interval": "monthly",
        "description": "All my sets, first.",
    },
)
print(res.json())

← Previous

Read the creator’s subscription tier

The creator’s payout balance

Questions? [email protected]