Guides

Developer Portal Setup

Applies to
Gateway+Developer Portal
Hosting
Managed EdgeManaged DedicatedDiffersSelf-Hosted
1 difference by hosting option
Managed Dedicated

Zuplo configures custom domains for your instance instead of Account Settings → Custom Domains. See Managed Dedicated: Custom Domains.

The Developer Portal is the self-serve storefront for your monetized API. Customers browse plans, subscribe, manage their API keys, and monitor usage — all without contacting your team. The portal is built on Zudoku, Zuplo's open-source API documentation framework.

What the portal provides

Once monetization is enabled, the Developer Portal gains these pages:

Pricing page — Displays all published plans with feature comparisons, pricing details, and subscribe buttons. Unauthenticated visitors see plans and pricing. Authenticated users see which plan they're currently on and get upgrade/downgrade options.

Subscription management — Lists all of a customer's subscriptions (current and past), shows the current billing period, and provides cancel/upgrade/downgrade actions.

Usage dashboard — Real-time view of quota consumption for the current billing period. Shows each metered feature's usage against its entitlement, with visual progress indicators.

API key management — API keys are displayed within the context of their subscription. Each subscription has its own key, making it clear which key corresponds to which plan. Customers can roll keys from this page.

Prerequisites

Before setting up monetization in the portal, ensure:

  1. Authentication is configured — The Developer Portal requires authentication so it can identify customers. Auth0, Clerk, or custom OpenID Connect providers are supported.
  2. Meters, features, and plans are created — At least one plan must be published.
  3. Stripe is connected — The billing provider must be linked for payment processing.

Enabling monetization in the portal

Add the monetization plugin to your Developer Portal configuration. Open docs/zudoku.config.tsx in your project and add the plugin:

ReactCode
import { zuploMonetizationPlugin } from "@zuplo/zudoku-plugin-monetization"; const config: ZudokuConfig = { // ... your existing config plugins: [ zuploMonetizationPlugin(), // ... any other plugins you have ], };

Save and deploy. Once the plugin is enabled, ensure:

  1. Stripe is connected (see Stripe Integration)
  2. At least one plan is published

Plugin options

Pass options to zuploMonetizationPlugin() in docs/zudoku.config.tsx. All options are optional.

OptionTypeDescription
pricing.titlestringHeading of the pricing page. Defaults to "Pricing".
pricing.subtitlestringText under the heading. Defaults to "See our pricing options and choose the one that best suits your needs.".
pricing.unitsRecord<string, string>Unit names for usage in plan cards, keyed by rate card or feature key. Defaults to "unit".
checkout.renderBeforeCheckout(props) => ReactNode | nullRenders your own step on /checkout before the customer goes to Stripe. See below.
ReactCode
zuploMonetizationPlugin({ pricing: { title: "Plans and pricing", subtitle: "Start free and upgrade as your traffic grows.", units: { api_requests: "request" }, }, });

Names ending in s are used as written; any other name is pluralized by adding an s (request becomes requests).

Ask questions before checkout

Use checkout.renderBeforeCheckout to collect information, such as company size or use case, before the customer reaches payment. The function receives these props:

PropDescription
planThe plan the customer chose on the pricing page.
onCompleteCall it after your own submit succeeds to continue to checkout.
onCancelCall it to abandon the purchase and return the customer to the pricing page.
ReactCode
zuploMonetizationPlugin({ checkout: { renderBeforeCheckout: ({ plan, onComplete, onCancel }) => { // Free plans that need no payment method skip the form. if (plan.paymentRequired === false) return null; return ( <form onSubmit={async (event) => { event.preventDefault(); const data = new FormData(event.currentTarget); const response = await fetch("/api/qualify", { method: "POST", body: data, }); // Only continue when the submit worked. if (response.ok) onComplete(); }} > <h1>Tell us about {plan.name}</h1> <input name="companySize" placeholder="Company size" required /> <button type="submit">Continue</button> <button type="button" onClick={onCancel}> Cancel </button> </form> ); }, }, });
  • Returning null skips the form and goes straight to checkout.
  • The /checkout route renders without the site layout, so what you return is the whole page.
  • The portal doesn't create a Stripe Checkout session until you call onComplete. If your submit fails and you don't call it, the customer never reaches Stripe.
  • Saving the answers is up to you. The portal doesn't store them.
  • This step runs only on the checkout page. It doesn't restrict API access, so treat it as qualification rather than a requirement.

Custom (contact sales) plans

A plan sold through your sales team shows a "Contact Sales" price line and a button that links to your contact page instead of Subscribe. Set these keys in the plan's Metadata field in the Zuplo Portal plan editor:

Metadata keyDescription
isCustomSet to "true" to mark the plan as a contact-sales plan.
contactUrlWhere the button goes: a URL, an email address, or a portal path such as /contact.
contactLabelButton text. Defaults to Contact Sales.
JSONCode
{ "isCustom": "true", "contactUrl": "sales@example.com", "contactLabel": "Talk to sales" }

An email address opens the customer's mail client, a portal path stays inside the portal, and a full URL opens in a new tab. Without a usable contactUrl, the plan shows "Contact Sales" with no button. A customer who already holds the plan sees Manage Subscriptions instead of the contact button.

Link customers straight to checkout for a plan with /checkout?planId=<id>, where <id> is the plan's ID. For example, use this from a pricing table on your marketing site.

What happens next depends on the customer's current subscription:

  • No subscription: Checkout starts for that plan.
  • A different plan: The plan-change flow starts.
  • The same plan, or a subscription that's canceled: The customer goes to Subscriptions to manage it.
  • Multiple subscriptions enabled: The link always starts a new subscription.

Visitors who aren't signed in are asked to sign in first, and a link without a planId goes to the pricing page.

Configuring the pricing page

Plan display order

Control plan display order from Services → Monetization in the Zuplo Portal. Reorder plans using drag-and-drop.

Feature comparison matrix

The pricing page automatically generates a feature comparison table from your plans' rate cards and features. Each plan column shows:

  • Monthly price (or "Free" / "Custom" for special tiers)
  • Included entitlements for each metered feature (e.g., "50,000 API Calls")
  • Static feature availability (checkmark/cross)
  • Overage pricing where applicable

Highlighted plans

To highlight a plan, open it in the Zuplo Portal, expand the plan's advanced settings, and turn on Mark as Popular. The pricing page shows a "Most Popular" badge on the plan and emphasizes its button.

Custom plan descriptions

Plans display their name and description fields on the pricing page. Set these when creating or updating a plan via the API.

Handling free plans

Free plans that don't require a payment method skip the Stripe Checkout flow entirely. Whether a plan requires a payment method is controlled by the paymentRequired property on the plan itself.

Usage dashboard

The usage dashboard shows real-time quota consumption for each metered feature on the customer's active subscription.

Each meter displays:

  • Current usage count
  • Entitlement (quota limit)
  • Usage percentage as a progress bar
  • Billing period start and end dates
  • Overage amount (if applicable)

The usage dashboard updates on each page load, showing current consumption against entitlements for all metered features.

Subscription management

The subscriptions page shows:

  • Active subscriptions with plan name, status, current period, and API key
  • API keys nested under their subscription for clarity
  • Quick actions: Upgrade, Downgrade, Cancel, Manage Billing (opens Stripe Customer Portal)
  • Past subscriptions with their final status and date range

API key display

API keys are displayed within the context of their subscription. This is a deliberate design choice — in the previous version, keys and subscriptions were shown separately, causing confusion about which key was associated with which plan.

Each subscription shows:

  • The API key value (click to reveal/copy)
  • Key creation date and last-updated time
  • Key status ("Active" or "Expiring")
  • A Roll API Key button

When a customer rolls a key, the portal creates a new current key. The old key keeps working for 7 days and then expires, which gives the customer time to update their API clients. The new key uses the same plan entitlements.

A key that is waiting to expire shows an "Expiring" badge. If the customer no longer needs it, they can remove it before the 7 days pass with Delete API key, which permanently deletes the key.

Theming and branding

The Developer Portal inherits your project's Zudoku theme. Monetization pages use the same fonts, colors, and layout as the rest of your portal.

Custom domain

The Developer Portal runs at https://your-project.zuplo.dev/docs by default. For production, configure a custom domain:

  1. Open Account Settings → Custom Domains in the Zuplo Portal
  2. Add your domain (e.g., developers.your-company.com)
  3. Configure the DNS records as instructed
  4. SSL is provisioned automatically

Your monetization pages, including the Stripe Checkout redirect flow, work seamlessly with custom domains.

Last modified on