Custom Theme Development Guide

Build your own website that plugs into Super Dodo Terminal and HostHelper. You control every pixel — the backend handles the rest.

Quick Start

1. Build your HTML/CSS/JS site in any editor you like
2. Open HostHelper → Website Settings → Step 4
3. Check "Use a custom website instead"
4. Pick your site folder and click Apply
5. HostHelper copies your files to the folder SDT serves from
6. Start your tunnel in Step 2 and your site is live

Folder Structure

Your root folder should look something like this. Not all pages are required — only build the ones your site needs.

your-site/
  index.html              ← home page (recommended)
  legal.html              ← terms / privacy (required)
  token-signup.html        ← account creation
  token-login.html         ← login
  token-forgot.html        ← token recovery
  token-profile.html       ← player profile / settings
  token-recovery.html      ← account recovery
  hosts.html               ← team host list (team mode)
  rules.html               ← rules page
  faq.html                 ← FAQ page
  alerts.html              ← alerts / announcements
  host-about.html          ← about the host
  subscriptions.html       ← subscription tiers
  pay.html                 ← payment page
  confirmation.html        ← payment confirmation
  requests.html            ← player requests
  report.html              ← player reports
  order-status.html        ← item/villager order tracker
  queue-status.html        ← visitor queue position tracker
  island-paradise.html     ← per-island page (one per island)
  assets/
    theme/                 ← your images, fonts, CSS

SDT serves these files from %AppData%\HostHelper\dodo-builder-preview-{mode}\ where {mode} is solo or team. HostHelper copies your folder there when you click Apply.

Special Page Behaviors

• / (root) — If there is at least one online island, SDT redirects GET / to /island-{slug}.html for the first online island. If no islands are connected, it serves index.html (or the fallback "still setting up" page if no files exist).
• island-{slug}.html — If a specific island page (e.g. island-paradise.html) doesn't exist, SDT will use any island-*.html it finds as a template. It injects three JavaScript constants into the template: const TARGET_ISLAND, const FALLBACK_NAME, and const ISLAND_SLUG. Your template page can use these to know which island to display.
• queue-status.html — When served via /queue/{slug}, SDT injects a small script that adds Done-button subtext from the queue config. Your page should have a "Done" button for players to end their queue session.
• order-status.html — Served when a visitor hits /order/{id} in a browser (with Accept: text/html). Your page should poll the order API for progress using the order ID from the URL.

The island-{slug} Convention

The "slug" is created by SDT by lowercasing the island name and removing spaces. So an island named "My Paradise" becomes slug myparadise, and its page would be island-myparadise.html. You can find the correct slug in the islandKey field on each island object from /api/public/status.

API Base URL

All API calls go to the same address your site is served from. In your JavaScript:

const API_BASE = window.location.origin;

This works because SDT serves both your pages and the API from the same server (port 7070). When visitors use your Cloudflare tunnel URL, window.location.origin points to the right place automatically.

Authentication

SDT has two layers of access: website access (form-based, via cookies) and Dodo Token accounts (email + token, via headers).

Website Access (Cookie-Based)

When a visitor first arrives, they may need to fill out a simple access form (player name, island name, contact info). This is handled by:

POST /api/access-request

const res = await fetch(`${API_BASE}/api/access-request`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    playerName: 'Luna',
    islandName: 'Moonisle',
    contactType: 'Discord',
    contactValue: 'luna#1234'
  })
});

On success, SDT sets a sdt_site_access cookie (HttpOnly, ~8 hour expiry). This cookie is sent automatically with every future request. No extra JavaScript needed — the browser handles it.

POST /api/logout — Clears the session. Returns { success: true }.

GET /api/access-status — Check the current visitor's access state. Returns:

Dodo Token (Header-Based)

Players sign up with an email and get a token back. Authenticated calls use two headers:

const headers = {
  'Content-Type': 'application/json',
  'X-Dodo-Email': localStorage.getItem('dodoEmail'),
  'X-Dodo-Token': localStorage.getItem('dodoToken')
};

Store the email and token in localStorage after login or signup so they persist across page loads.

How Access Tiers Work

SDT determines a visitor's access tier in this priority order:

1. sdt_site_access cookie — if valid, uses the tier stored in the session
2. IP approval list — if the visitor's IP was approved via the access form
3. X-Dodo-Email header — if the email matches a centrally-subscribed paid account, tier is "Paid"
4. None of the above — tier is "None" (limited access)

When Dodo Codes Are Hidden

The dodoCode field on each island will be empty ("") or have a special value when:

• Visitor is banned → ""
• Visitor has no website access (tier is "None") → ""
• Island is password-protected and visitor hasn't unlocked it → ""
• Island is in queue mode → "" (code shown only via queue status endpoint when it's your turn)
• Island is monetized and visitor has no paid access → "PAID" (literal string)

Password-Protected Islands

POST /api/private-unlock

const res = await fetch(`${API_BASE}/api/private-unlock`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    islandKey: 'paradise',
    password: 'secret123'
  })
});

On success, sets a per-island unlock cookie (sdt_unlock_{islandKey}). The requiresWebsitePassword and websitePasswordUnlocked fields on each island in /api/public/status tell you whether to show a password prompt.

GET /api/website-access-config — Returns the list of access rules per island (with passwords stripped), including IsUnlocked and IsWebsiteApproved for the current visitor.

API Endpoints

Quick Reference

Every endpoint at a glance. Auth column: None = open, Cookie = website access cookie, Token = X-Dodo-Email + X-Dodo-Token headers, Token/QS = headers or query string.

Island Data (the main one)

GET /api/public/status

This is the big one. Returns everything about the host's islands, visitor counts, queue state, and more. No login required.

const res = await fetch(`${API_BASE}/api/public/status`);
const data = await res.json();

Top-Level Fields:

Each island in the array:

GET /api/public/islands returns the same data (it's an alias).

Subscriptions

GET /api/public/subscriptions

Returns available subscription plans and which islands are monetized. No login required.

Top-level fields:

Each plan:

Each island:

Account System

Sign Up

POST /api/public/access/request

Creates a new player account.

const res = await fetch(`${API_BASE}/api/public/access/request`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'player@example.com',
    dateOfBirth: '2000-01-15',
    playerIslandPairs: [
      { playerName: 'Luna', islandName: 'Moonisle' }
    ],
    contactType: 'Discord',
    contactValue: 'luna#1234',
    centralOptIn: true
  })
});
const data = await res.json();
// data.success === true
// data.token → store in localStorage
// data.centralLinked → whether central DB account was created

Error codes: 429 rate limit, 400 validation, 403 under 18, 409 email already exists, 500 server error. All return { success: false, error: "message" }.

On success: { success: true, message: "...", token: "abc123", centralLinked: true/false }. Store email and token in localStorage.

Log In

POST /api/public/access/login

const res = await fetch(`${API_BASE}/api/public/access/login`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'player@example.com',
    token: 'abc123def456'
  })
});

Success response:

{
  "success": true,
  "playerIcon": "icon-name",
  "playerIconUrl": "assets/player-icons/icon-name.png",
  "playerIslandPairs": [
    { "playerName": "Luna", "islandName": "Moonisle" }
  ],
  "contactRevoked": false,
  "centralLinked": true,
  "contacts": [
    { "contactType": "Discord", "contactValue": "luna#1234" }
  ],
  "preferredContactType": "Discord"
}

Error codes: 400 missing fields, 401 wrong credentials, 403 banned account ("This account is no longer allowed to sign in.").

Recover Token

POST /api/public/access/reset-token

{
  "email": "player@example.com",
  "contactType": "Discord",
  "contactValue": "luna#1234",
  "dateOfBirth": "2000-01-15"
}

On success: { success: true, message: "...", token: "newToken123" }. Most failures return a generic error message to prevent account fishing.

Update Profile

POST /api/public/access/profile/update — update player/island pairs. Requires auth headers.

Body: { playerIslandPairs: [ { playerName, islandName }, ... ] }

Update Contact Info

POST /api/public/access/contact/update — update contact methods. Requires auth headers.

Two body formats are accepted. To update all contacts at once:

{
  "contacts": [
    { "contactType": "Discord", "contactValue": "luna#1234" },
    { "contactType": "Twitter", "contactValue": "@luna" }
  ],
  "preferredContactType": "Discord"
}

Or to update just the preferred contact's value:

{
  "contactValue": "luna#5678"
}

Success: { success: true, message: "Contact info updated. The host has been notified." }

Errors: 401 not logged in, 400 invalid contact info, 500 server error.

Set Player Icon

POST /api/public/access/icon — set the player's display icon. Body includes email, token, playerIcon. Returns 403 if banned.

Delete Account

POST /api/public/access/delete-account — permanently deletes the account. Requires auth headers. Returns { success: true, message: "Your account has been deleted." }.

Link to Central Database

POST /api/public/access/central-opt-in — links the account to the central Dodo Suite directory. Requires auth headers. Various error codes possible (503 central server down, 409 already linked, 500 failure).

Rules

POST /api/public/access/agree-rules — records that the player agreed to the rules.

GET /api/public/access/rules-status — checks if they've agreed. Returns rulesAgreed (true/false) and rulesAgreedUtc.

Both accept auth via headers or query params (?dodoEmail=...&dodoToken=...). Returns 403 if banned.

Messages (Inbox)

GET /api/public/access/messages — fetches the player's inbox. Requires auth headers.

Returns { success: true, messages: [...] } with an array of message objects.

POST /api/public/access/messages/mark-read — marks all messages as read.

Requests & Reports

POST /api/public/requests/submit — Requires auth headers.

{
  "subject": "Can I visit?",
  "requestType": "General",
  "playerName": "Luna",
  "islandName": "Moonisle",
  "details": "I'd love to come catalog some items."
}

POST /api/public/reports/submit — Requires auth headers.

{
  "reportType": "Website",
  "subject": "Bug on island page",
  "playerName": "Luna",
  "islandName": "Moonisle",
  "details": "The queue button doesn't appear.",
  "category": "Bug",
  "subCategory": "UI"
}

Visitor Queue System

The visitor queue lets players line up to visit an island. It uses a queue ID + secret model — players get both when they join and use them to check status and signal when they're done.

Get Queue Entries for an Island

GET /api/queue/island/{slug} — No login required.

const res = await fetch(`${API_BASE}/api/queue/island/paradise`);
const data = await res.json();

Response:

{
  "queueLength": 3,
  "entries": [
    {
      "Position": 1,
      "PlayerName": "Luna...",
      "StayMinutes": 15,
      "EstimatedEtaMinutes": 0,
      "Status": "turn"
    },
    {
      "Position": 2,
      "PlayerName": "Alex...",
      "StayMinutes": 30,
      "EstimatedEtaMinutes": 12,
      "Status": "next"
    }
  ]
}

If queue mode is off or the island doesn't exist, returns queueLength: 0 and an empty entries array.

Get Queue Configuration

GET /api/queue-config/{slug} — No login required.

const res = await fetch(`${API_BASE}/api/queue-config/paradise`);
const data = await res.json();

Response (200):

{
  "preSignupMessage": "Welcome! Join the queue below.",
  "waitingMessage": "Hang tight, you're in line!",
  "yourTurnMessage": "It's your turn! Here's your Dodo code.",
  "stayTimeEnabled": true,
  "stayTimeOptionsMinutes": "15,30,45,60",
  "defaultStayMinutes": 15,
  "doneButtonSubtext": "Use this button when you're completely done..."
}

Returns 404 with { error: "Queue config not found" } if the island doesn't exist or queue mode is off.

Join Queue

POST /api/queue/join — Requires Dodo Token auth headers.

const res = await fetch(`${API_BASE}/api/queue/join`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Dodo-Email': localStorage.getItem('dodoEmail'),
    'X-Dodo-Token': localStorage.getItem('dodoToken')
  },
  body: JSON.stringify({
    islandSlug: 'paradise',
    playerName: 'Luna',
    islandName: 'Moonisle',
    stayMinutes: 15
  })
});

Success (200):

{
  "queueId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "secret": "xYz123aBcDeFg",
  "position": 2
}

Save queueId and secret — you need both for all future queue calls. The queueId is a 32-character hex string (GUID without dashes). The secret is a random string.

Errors: 401 not logged in, 400 missing fields or queue not enabled.

Check Queue Status

GET /api/queue/{queueId}?s={secret} — No login required (possession of ID + secret is the access model).

const res = await fetch(`${API_BASE}/api/queue/${queueId}?s=${encodeURIComponent(secret)}`);
const data = await res.json();

Response (200):

{
  "Status": "waiting",
  "QueuePosition": 2,
  "EstimatedWaitMinutes": 12,
  "DodoCode": "",
  "StaySecondsRemaining": null,
  "IslandName": "paradise",
  "WaitingMessage": "Hang tight!",
  "YourTurnMessage": "Here's your Dodo code!"
}

Returns 404 with { error: "not_found", status: "error" } if the queue ID or secret is wrong.

Poll this every 3–5 seconds on your queue-status.html page. When Status changes to "turn", show the Dodo code and a "Done" button.

Signal Done

POST /api/queue/{queueId}/done — Tells the queue you're finished.

Secret can be passed as query ?s={secret} or in the body as { "secret": "..." }.

Success: { "ok": true }

Errors: 400 if it's not your turn or the secret is wrong. Only the active visitor (the one whose Status is "turn") can call done. Players who are still waiting cannot leave the queue via this endpoint.

Villager Injection Queue

This is a separate system from the visitor queue above. This tracks villager injections (moving villagers onto islands).

GET /api/queue-status — Requires website access (logged in or form submitted).

Optional query: ?islandIndex={n} for per-island status.

Response:

{
  "QueueLength": 2,
  "Pending": ["Raymond", "Marshal"],
  "PendingLines": ["Raymond in queue for Alex", "Marshal in queue for Luna"],
  "SecondsUntilNextInjection": 45,
  "LastInjectionTime": "2026-04-06T12:00:00.0000000Z",
  "LastInjectedName": "Raymond",
  "IslandName": "Paradise"
}

If the visitor doesn't have website access, returns an empty default object (zeros and empty arrays), still with status 200.

Villager Requests

GET /api/pool-villagers — Returns the available villager pool. Requires website access (returns [] if not approved).

[
  { "InternalName": "cat23", "DisplayName": "Raymond" },
  { "InternalName": "squir09", "DisplayName": "Marshal" }
]

Note: PascalCase field names. This is the raw pool of villagers the host has available for injection.

GET /api/villagers — Returns the list of available villagers for request forms. No login required.

{
  "villagers": ["Raymond", "Marshal", "Judy"],
  "options": [
    { "internalName": "cat23", "displayName": "Raymond" },
    { "internalName": "squir09", "displayName": "Marshal" }
  ]
}

POST /api/request-villager — Submit a villager request. Requires website access.

{
  "VillagerInternalName": "cat23",
  "VillagerName": "Raymond",
  "IslandIndex": 0,
  "PickupPlayerName": "Luna",
  "PickupIslandName": "Moonisle"
}

Success (200):

{
  "success": true,
  "message": "Raymond has been queued!",
  "position": 2,
  "etaSeconds": 345
}

If injection is unavailable, position and etaSeconds may be omitted. 403 if access blocked, 429 for rate limit or cooldown, 400 for validation errors.

GET /api/requests — Returns all villager request records as a JSON array. Requires website access; returns [] if not approved.

Item Ordering

SDT has a built-in order system. The dashboard server proxies order requests to the internal order API — your theme just calls the same URLs.

Get Item Catalog

GET /items — Returns the full item catalog. No login required.

{
  "items": [
    {
      "hex": "1A2B",
      "name": "Ironwood Dresser",
      "category": "Furniture",
      "series": "Ironwood",
      "colours": ["Brown"],
      "interact": "Table",
      "diy": true,
      "itemTag": "HousewareTable",
      "hha": "3",
      "hha2": "3",
      "imageUrl": "/api/catalog/images/ironwood-dresser.png",
      "stackSize": 1,
      "variations": [
        {
          "name": "Birch",
          "id": "0",
          "hex": "1A2B0000",
          "filename": "ironwood-dresser-birch.png",
          "imageUrl": "/api/catalog/images/ironwood-dresser-birch.png",
          "colours": ["Beige"]
        }
      ]
    }
  ],
  "categories": ["Furniture", "Clothing", "Wallpaper"],
  "series": ["Ironwood", "Rattan"]
}

If the catalog file doesn't exist on the host's setup, returns {}.

Get Order Form Config

GET /api/order-config/{slug} — Returns order form settings for an island. No login required.

{
  "allowStayTimeSelection": true,
  "stayTimeOptionsMinutes": "3,5,10,15",
  "multiZoneEnabled": false
}

Returns 404 plain text "Order config not found" if the island doesn't exist or isn't an order island.

Submit an Order

POST /order — Submits an item order.

const res = await fetch(`${API_BASE}/order`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Dodo-Email': localStorage.getItem('dodoEmail'),
    'X-Dodo-Token': localStorage.getItem('dodoToken')
  },
  body: JSON.stringify({
    villagerName: 'Luna',
    items: ['09C9', '1A2B'],
    islandName: 'Paradise',
    stayMinutes: 5
  })
});

Request body fields:

Success (200):

{
  "success": true,
  "orderId": "ORD-143022-4521",
  "queuePosition": 3,
  "estimatedWaitMinutes": 15,
  "message": "Order queued! You are #3 in queue."
}

Save orderId — you need it for the status page.

Error responses:

SDT also enforces a per-player cooldown at the dashboard level — if OrderCooldownEnabled is on for the island, repeat orders within the cooldown window return 429 with { message: "You can only submit one order every X minutes. Please wait and try again." }.

Check Order Status

GET /order/{orderId} — Returns order status as JSON (when called from JavaScript), or serves your order-status.html page (when opened in a browser).

const res = await fetch(`${API_BASE}/order/${orderId}`);
const data = await res.json();

Response (200):

{
  "orderId": "ORD-143022-4521",
  "status": "ReadyForPickup",
  "queuePosition": null,
  "estimatedWaitMinutes": null,
  "dodoCode": "ABC12",
  "villagerName": "Luna",
  "itemCount": 5,
  "zoneId": 1,
  "zoneX": 10,
  "zoneY": 20,
  "zoneWidth": 5,
  "zoneHeight": 5,
  "zoneAssignedAt": "2026-04-06T12:00:00Z",
  "zoneCooldownEndsAt": "2026-04-06T12:10:00Z",
  "islandName": "Paradise",
  "createdAt": "2026-04-06T11:55:00Z",
  "visitorArrived": false,
  "visitorLeft": false,
  "wasNoShow": false,
  "completedAt": null,
  "failureReason": null,
  "queueMessages": {
    "waitingSolo": "Hang tight, your order is being prepared!",
    "yourTurnSolo": "Your items are ready! Here's your Dodo code.",
    "waitingTeam": "Hang tight!",
    "yourTurnTeam": "Items ready!"
  },
  "lineItems": [
    {
      "hexId": "0x09C9",
      "displayName": "Gold Nugget",
      "sprite": "GoldNugget.png",
      "catalogImage": "09C9.png"
    }
  ],
  "queueOverview": {
    "slots": [
      { "slot": 0, "isEmpty": false, "playerName": "Alex", "itemCount": 3, "isYou": false },
      { "slot": 1, "isEmpty": false, "playerName": "Luna", "itemCount": 5, "isYou": true },
      { "slot": 2, "isEmpty": true, "playerName": "", "itemCount": 0, "isYou": false }
    ],
    "matchedInQueue": true,
    "yourWaitPosition": 1,
    "totalWaiting": 2,
    "totalInQueue": 2,
    "yourPosition": 1,
    "behindCount": 1
  }
}

Key fields:

Returns 404 with { error: "Order not found" } if the ID doesn't exist.

Poll this every 3–5 seconds on your order-status.html page. Show the Dodo code when status is "ReadyForPickup" or "WaitingForArrival".

Mark Order Complete ("I'm Done")

POST /order/{orderId}/complete — Player signals they're done picking up items.

Success: { success: true, message: "Thanks for visiting!" }

Errors: 400 missing ID, 404 order not found.

Get Order Queue

GET /queue — Returns the full order queue with wait times and zone info. Useful for a queue display page.

{
  "queueLength": 3,
  "estimatedTotalWaitMinutes": 15,
  "minutesPerOrder": 5,
  "orders": [
    {
      "position": 1,
      "villagerName": "Luna",
      "status": "Processing",
      "itemCount": 5,
      "zoneId": 1,
      "zoneState": "Queued",
      "estimatedWaitMinutes": 5,
      "createdAt": "2026-04-06T11:55:00Z"
    }
  ],
  "zones": [
    {
      "zoneId": 1,
      "state": "InUse",
      "assignedOrderId": "ORD-143022-4521",
      "cooldownEndsAt": "2026-04-06T12:10:00Z",
      "x": 10, "y": 20, "width": 5, "height": 5
    }
  ]
}

Get Dashboard / Status

GET /status (or /, /dashboard, /all) — Returns full server state: bot connection, queue, stats, preset list, time selection options, and sprite availability. Good for building a host-facing dashboard or debugging.

Preset Ordering

If the host has presets enabled, players can order a preset by name instead of picking individual items:

{
  "villagerName": "Luna",
  "preset": "starter-pack"
}

GET /preset/{name}/preview — Preview a preset's items before ordering. Returns item hex IDs, sprite names, and counts.

Other Order Paths

These paths are also handled: /form (HTML order form), /stats (order statistics), /test (test order), /help (endpoint list), /sprites/{name}.png (item sprites), /sprites/mapping (sprite name mapping).

Island Catalog

GET /api/catalog/{islandKey}/data — Returns island-specific catalog JSON. No login required.

GET /api/catalog/{islandKey}/overview — Returns island catalog overview as a PNG image.

GET /catalog/{islandKey} — SDT serves a built-in catalog viewer HTML page (not your theme).

GET /api/catalog/images/{filename} — Serves individual item images. Cached for 7 days.

Island Images

GET /api/map/{islandKey} — Island map image. Add ?view=team for team map variant.

GET /api/boarding-pass/{islandKey} — Boarding pass image.

GET /api/island-info-icon/{islandKey} — Island info icon.

GET /api/zone-map/{islandKey} — Zone map image.

All return PNG image data or 404. No login required.

Team Host Feed

GET /api/team-host-feed — Returns host info, all islands, and inbox items for team mode. This is what HostHelper pulls from each team member's SDT instance.

Optional query params:

Response (200): All field names are PascalCase (unlike /api/public/status which uses camelCase).

{
  "Host": {
    "HostDisplayName": "Luna's Islands",
    "FacebookProfileUrl": "",
    "AboutPageUrl": "",
    "HostAboutMeRichTextXaml": "",
    "HostAboutMeHtml": "<p>Welcome!</p>"
  },
  "Islands": [
    {
      "IslandName": "Paradise",
      "HostName": "Luna",
      "DodoCode": "ABC12",
      "Status": "Online",
      "IsOnline": true,
      "VisitorCount": 3,
      "IsQueueMode": false,
      "IsOrderIsland": true,
      "VillagerRequestsEnabled": false,
      "...": "all DashboardIslandInfo fields in PascalCase"
    }
  ],
  "InboxItems": [
    {
      "Id": "abc-123",
      "Type": "Request",
      "SubmitterEmail": "player@example.com",
      "PreferredContactType": "Discord",
      "PreferredContactValue": "luna#1234",
      "ContactReachOutSummary": "Discord: luna#1234",
      "ReceivedUtc": "2026-04-06T12:00:00Z",
      "Subject": "Can I visit?",
      "RequestType": "General",
      "PlayerName": "Luna",
      "IslandName": "Moonisle",
      "Details": "I'd love to come catalog!",
      "IsRead": false
    }
  ],
  "GeneratedUtc": "2026-04-06T12:00:00Z"
}

Errors: 404 if team feed is disabled, 401 if token is wrong.

Team villager relay: POST /api/team-host-feed/request-villager works the same as POST /api/request-villager but is called by HostHelper on behalf of a visitor. Requires the feed token query param.

PayPal Payments

Before showing a "Subscribe" or "Buy" button, check if the player is logged in (email + token in localStorage). If not, show a "Log in to subscribe" message instead and link to your login page.

Create Subscription

POST /api/public/payments/paypal/create-subscription

const res = await fetch(`${API_BASE}/api/public/payments/paypal/create-subscription`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Dodo-Email': localStorage.getItem('dodoEmail'),
    'X-Dodo-Token': localStorage.getItem('dodoToken')
  },
  body: JSON.stringify({
    planId: 'P-ABC123',
    successUrl: `${window.location.origin}/confirmation.html`,
    cancelUrl: `${window.location.origin}/subscriptions.html`,
    email: localStorage.getItem('dodoEmail'),
    token: localStorage.getItem('dodoToken')
  })
});
const data = await res.json();
if (data.success) {
  window.location.href = data.checkoutUrl;
}

Success (200):

{
  "success": true,
  "checkoutUrl": "https://www.paypal.com/webapps/billing/subscriptions?ba_token=...",
  "subscriptionId": "I-ABC123XYZ",
  "approvedAccessEntryId": "entry-id-here"
}

Redirect the player to checkoutUrl. PayPal handles the rest.

Error responses:

Create One-Time Payment

POST /api/public/payments/paypal/create-order — same auth requirements as subscriptions.

{
  "amount": "5.00",
  "currency": "USD",
  "successUrl": "https://your-site.com/confirmation.html",
  "cancelUrl": "https://your-site.com/subscriptions.html",
  "email": "player@example.com",
  "token": "abc123def456"
}

Success (200):

{
  "success": true,
  "checkoutUrl": "https://www.paypal.com/checkoutnow?token=...",
  "orderId": "PAYPAL-ORDER-ID",
  "approvedAccessEntryId": "entry-id-here"
}

Same error codes as create-subscription above.

Webhook

The PayPal webhook (POST /api/public/payments/paypal/webhook) is called by PayPal automatically — you don't need to handle it in your frontend. It processes subscription activations and payment completions behind the scenes.

Flows

Step-by-step walkthroughs for the most common things your site will do.

Login / Signup

1. Player lands on token-signup.html
2. Fills in email, DOB, player name(s), island name(s), contact info
3. POST /api/public/access/request — get token back
4. Store email + token in localStorage — redirect to index.html
5. Return visits: token-login.html → POST /api/public/access/login
6. Login response includes playerIslandPairs, contacts, playerIcon, etc.
7. Forgot token: token-forgot.html → POST /api/public/access/reset-token

Visitor Queue

1. Player visits island-{slug}.html
2. Page polls GET /api/public/status for island data
3. If isQueueMode is true, show a "Join Queue" button
4. Load queue config from GET /api/queue-config/{slug} for messages and stay time options
5. Player clicks join → POST /api/queue/join (requires auth headers)
6. Save the queueId and secret from the response
7. Redirect to queue-status.html (pass queueId and secret via URL hash or localStorage)
8. queue-status.html polls GET /api/queue/{queueId}?s={secret} every 3–5 seconds
9. Show position, estimated wait, and the waiting message
10. When Status is "turn" → show the DodoCode and the "your turn" message
11. Show StaySecondsRemaining as a countdown timer
12. When player is done → POST /api/queue/{queueId}/done (with secret)
13. Status becomes "done" — show a thank-you / goodbye message

Orders (Items)

1. Player visits island-{slug}.html
2. Check isOrderIsland or isOrderBotIsland from /api/public/status
3. Load item catalog from GET /items (hex IDs, names, categories, images)
4. Load order config from GET /api/order-config/{slug} for stay time options
5. Player picks items and stay time, enters their name
6. POST /order with villagerName, items (hex ID array), stayMinutes
7. Response includes orderId, queuePosition, estimatedWaitMinutes
8. Redirect to /order/{orderId} (serves order-status.html in a browser)
9. order-status.html extracts the order ID from the URL
10. Poll GET /order/{orderId} every 3–5 seconds for status JSON
11. When status is "ReadyForPickup" → show dodoCode and lineItems
12. Player picks up items and clicks "I'm Done" → POST /order/{orderId}/complete

Villager Requests

1. Player visits island-{slug}.html
2. Check villagerRequestsEnabled from /api/public/status
3. Load villager list from GET /api/villagers
4. Player picks a villager → POST /api/request-villager
5. Response includes position and etaSeconds
6. Show queue position and estimated wait time

Subscriptions / Payments

1. Player visits subscriptions.html
2. GET /api/public/subscriptions for available plans (no login needed — show plans to everyone)
3. Player picks a plan → check if logged in (email + token in localStorage)
4. Not logged in → redirect to token-login.html (or show inline login prompt), then come back
5. Logged in → go to pay.html with the selected planId
6. POST /api/public/payments/paypal/create-subscription with planId, successUrl, cancelUrl, email, token
   (include email + token in both the request body and as X-Dodo-Email / X-Dodo-Token headers)
7. SDT auto-links the subscription to their Dodo Token account
8. Response includes checkoutUrl → redirect player to PayPal
9. PayPal redirects back to confirmation.html after payment
10. Webhook fires automatically (nothing for you to do) — SDT activates their paid access

External Resources

These external sources are used by the built-in theme and available for custom sites too:

Page Checklist

Tips

• Unknown API paths return a redirect to /, not a 404. Check for non-JSON responses in your error handling.
• The .custom-theme file in your preview folder tells SDT you're running a custom site. Don't delete it.
• CORS is wide open — SDT sets Access-Control-Allow-Origin: * on all responses, so your fetch() calls work from anywhere.
• You don't need all the pages. Start with index.html and legal.html, add more as you go.
• PascalCase vs camelCase — Most top-level response fields use camelCase. Queue entry DTOs and villager objects inside arrays use PascalCase (Position, Name, State). Watch for this when parsing.
• Rate limits — Signup, access requests, password attempts, and villager requests have per-IP rate limits. Handle 429 responses gracefully with a retry message.
• The sdt_site_access cookie lasts about 8 hours. After it expires, visitors need to re-submit the access form or log in again.
• Dynamic island pages — If you only want one island page template, name it island-template.html (or any island-*.html name). SDT will inject const TARGET_ISLAND, const FALLBACK_NAME, and const ISLAND_SLUG at the top of the page so your JavaScript knows which island to display.

Related pages:

• Your Website — overview of website options
• HostHelper — setting up HostHelper
• Site Setup on Set Up Your Dodo Suite — Stable Domain Setup, Dodo Site Setup, and Dodo Site Editing
• Accounts & Central Database — how the account system works