Publisher API

You already have a Discord bot with commands, buttons, and interaction handlers. You do not replace your bot with ours. You hook into your own interactions — whenever it makes sense in your bot's flow — and call our two endpoints to deliver an ad.

Your bot requests an ad, your bot sends the ad embed, your bot confirms delivery. Our API handles everything else: ad selection, billing, targeting, and payout. Your existing commands and features stay completely intact.

Standard payout is 35% of what the advertiser pays per event. Send optional member data (member_data_provided, user_roles, is_booster) and earn 45%. Payout applies to views, clicks, joins, and stays — whatever campaign type the ad uses.

Authentication

All requests must include an Authorization header with your API key as a Bearer token. Your external_bot_id goes in the request body.

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

The 2-step flow

Drop-in snippets for your existing bot. Copy the helper and the two handlers into your existing interaction handler — do not replace your bot. All snippets use a cv: prefix on customIds so they never clash with your own. The API key and base URL are pre-filled if you arrived from the dashboard.

Returns an ad and a signed view token. Always check if ad is null before sending anything to Discord.

{
  "ok": true,
  "ad": {
    "ad_id": "uuid",
    "banner_url": "https://...",          // embed image
    "button_name": "Visit site",          // link button label
    "click_url": "https://.../c/TOKEN",   // link button URL — tracks clicks
    "embed_color": "#6D5EFC",
    "target_type": "views",               // "views" | "clicks" | "joins" | "stays"
    "join_url": "https://.../j/TOKEN"     // only present for joins/stays campaigns
  },
  "view_token": "eyJ...",                 // pass to views/confirm
  "expires_in_seconds": 120
}

{
  "ok": true,
  "ad": null,
  "view_token": null,
  "denied_reason": "user_daily_cap"  // see Errors section
}

When ad is null, skip silently — do not send any embed.

Records the delivery and triggers billing. Call this after the Discord message is sent. This is when your earnings are recorded.

// Billed
{ "ok": true, "billed": true, "ad_id": "uuid", "auto_paused": false, "daily_cap_reached": false }

// Not billed
{ "ok": true, "billed": false, "reason": "token_expired" }

auto_paused: true means the advertiser's balance hit zero on this confirm — the ad has been automatically paused. Informational only, no action needed from your bot. daily_cap_reached: true means the advertiser's daily spend limit was hit — same, informational only.

Campaign types

The ad.target_type field in the ads/request response tells you what kind of campaign was served. Your core integration is the same for all types — request, send embed, confirm. Payouts differ because advertisers pay different rates per action.

Joins & stays

Join and stay campaigns pay when a user joins the advertiser's Discord server (and optionally stays for a set duration). Your integration only differs in which URL you use as the button — everything else is the same.

A stay campaign requires the user to remain in the server for a set duration before payout is recorded. This is tracked automatically by our backend after the join — no additional code or events needed from your bot.

Premium data — 45% payout

Standard payout is 35% of advertiser spend. If your bot has the Server Members Intent (a privileged intent from the Discord Developer Portal), you can send per-user member data on each ad request and earn 45%.

User roles are passed through an AI classifier that infers demographic signals — gender, age range, device type, language, interests — based on role names (e.g. "He/Him", "Mobile", "PlayStation", "18+"). These signals improve ad targeting accuracy over time, which raises advertiser CPMs and your earnings. Inference only runs once per user per server. The data is never sold and is only used for targeting within Cordvertise.

Errors & denials

Rate limits & delivery caps

Idempotency

Calling views/confirm multiple times with the same event_id returns already_confirmed and does not double-bill. Safe to retry on network failure.