Recipe: a catalog site with free, subscription and paid access

How to put a creator's videos on your own site — free titles, members-only titles and pay-per-view titles — with what the platform does today. Every behaviour below is read from the running code; where something you would expect is missing, this page says so.

1. The access model of a video

Four fields on every video decide who can play it. You set them with PATCH /videos/:id and read them from GET /videos and GET /videos/:id.

The checks stack: visibility is applied first, then the membership gate, then the purchase gate. A PUBLIC video with isPaid: true is listed publicly but still needs a purchase to play. When a video is both paid and tier-gated, a completed purchase (or an access-key grant) by a signed-in viewer opens it without the subscription.

# Free title
curl -s -X PATCH "https://api.dcast.pro/api/v1/videos/VIDEO_ID" -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" -d '{"visibility":"PUBLIC","isPaid":false,"requiredTierId":null}'

# Pay-per-view title, listed on the channel
curl -s -X PATCH "https://api.dcast.pro/api/v1/videos/VIDEO_ID" -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" -d '{"visibility":"PUBLIC","isPaid":true,"price":4.99}'

# Members-only title (tier id from GET /tiers)
curl -s -X PATCH "https://api.dcast.pro/api/v1/videos/VIDEO_ID" -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" -d '{"visibility":"TIER_EXCLUSIVE","requiredTierId":"TIER_ID"}'

Tiers are created with POST /tiers (needs a FULL_ACCESS key or finance:write) — see Monetization.

2. Build the catalog

Call these from your server. The pk_ key is a secret: never ship it to the browser.

# Your whole library, 50 per page (server-side)
curl -s -H "Authorization: Bearer pk_YOUR_KEY_HERE" "https://api.dcast.pro/api/v1/videos?page=1&limit=50"

# One title with its playback block
curl -s -H "Authorization: Bearer pk_YOUR_KEY_HERE" "https://api.dcast.pro/api/v1/videos/VIDEO_ID"
# → data.playback = { playable, hls, embed, playUrl, accessTokenUrl, thumbnail, requiresToken }

Keep your catalog fresh with webhooks (video.processing.completed, video.processing.failed) instead of polling — see Webhooks.

3. Playback

Option A — the embeddable player (recommended for paid content)

Put playback.embed (https://dcast.tv/embed/VIDEO_ID) in an <iframe>. Any domain may embed it unless the creator has set an embed allowlist (Account). The player asks the platform for a pass itself and, when it is refused, shows a paywall that depends on the reason:

Payment requests made inside the player come from the DCAST player origin, so the integration-domain requirement described in Monetization → Domain verification applies to your own /checkout/* calls, not to the iframe.

Option B — your own player

Read playback.requiresToken on GET /videos/:id:

• false — playback.hls plays as-is in any HLS player.
• true — playback.hls answers 403 until you obtain a pass from playback.accessTokenUrl.

accessTokenUrl is GET https://api.dcast.pro/api/videos/VIDEO_ID/access-token. It is not part of /api/v1 and does not read your pk_ key: it decides for the viewer. It admits a request when one of these holds:

curl -s "https://api.dcast.pro/api/videos/VIDEO_ID/access-token?accessCode=A1B2C3D4E5F60718"

# 200
{ "success": true,
  "masterUrl": "https://<delivery-host>/video/VIDEO_ID/master.m3u8?token=...",
  "expiresIn": 300 }

# 401 (sign-in needed) or 403 (refused)
{ "error": "Access denied", "reason": "payment_required", "message": "...",
  "paywall": { "requiresPurchase": true, "requiresSubscription": false, "requiresTier": false,
               "price": 4.99, "tierId": null, "tierName": null, "creatorId": "..." } }

Play masterUrl. The pass for the master playlist is valid for 300 seconds; segment and key passes for 1800 seconds. A 503 with DELIVERY_WORKER_UNAVAILABLE means no delivery host could be chosen at that moment — retry.

4. Selling

The Partner API checkout endpoints buy as the key owner

POST /checkout/subscription (body tierId, creatorUsername, optional interval, successUrl, cancelUrl) and POST /checkout/video (body videoId, optional successUrl, cancelUrl) return { sessionId, checkoutUrl } for a hosted Stripe Checkout page. The buyer is always the account that owns the API key. There is no customerEmail or userId field, and sending an X-User-Token for a different user is refused 401 INVALID_USER_TOKEN (“Multi-user desktop flow via a shared pk_ key is currently disabled”).

Consequence: with one key for your site, every checkout would be bought by, and granted to, your own account — not to the viewer who clicked. These endpoints fit an app where each end user holds their own key; they cannot run a storefront for many viewers. POST /checkout/video also refuses a buyer account with no Stripe customer record yet (400, “Customer not found. Complete a platform purchase first.”). Both are origin-locked: see domain verification.

What works for a multi-viewer site today

• Let the embedded player sell. Paid videos are bought inside the player by email; subscriptions go through a DCAST sign-in. The money goes to the creator's connected Stripe account.
• Author access keys for people the creator wants to let in. Keys are created in the DCAST dashboard (videos: Content → Videos, access keys panel), one at a time or in bulk (up to 1000 per request). A key is a 16-character code with a seat rule (one screen at a time, or unlimited), an optional expiry and an optional redemption limit. The viewer types it into the embedded player, or your player passes it as ?accessCode=. The video pass accepts only keys scoped to that exact video. Keys cannot be created through the Partner API today.
• Free membership for a known email: POST /subscribers with { email, tierId? } creates an active subscription on a free tier (or with no tier), creating a DCAST account for that email if none exists. It opens SUBSCRIBERS videos for that account once the viewer is signed in to DCAST as that email. Paid tiers are refused 400 PAID_TIER_USE_CHECKOUT.

Reconciling sales

GET /purchases, GET /videos/:videoId/purchases and GET /monetization/payments list completed sales of your content (the last one needs a FULL_ACCESS key or finance:read). The purchase.completed webhook is sent to the creator when a POST /checkout/video session completes; purchases made inside the embedded player do not emit it today, so reconcile those from the list endpoints. subscription.created, subscription.renewed and subscription.cancelled are in the event catalogue.

5. Not available today

6. Checklist

1. Create a FULL_ACCESS key; keep it on your server.
2. Create tiers (POST /tiers) and set each video's visibility, isPaid/price, requiredTierId.
3. Make sure the creator's payout account is connected: GET /monetization/connect-status must say connected: true.
4. Render the catalog from GET /videos (or GET /channel/:username/videos for public titles only).
5. Play with the embedded player for anything paid or members-only; use your own player only where requiresToken is false or you hold a code.
6. If your site calls /checkout/* from its own pages, declare and verify its domain first.
7. Subscribe to webhooks and reconcile sales from the purchases endpoints.