Developer Portal Setup
- Applies to
- Gateway+Developer Portal
- Hosting
- Managed EdgeManaged DedicatedDiffersSelf-Hosted
1 difference by hosting option
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:
- Authentication is configured — The Developer Portal requires authentication so it can identify customers. Auth0, Clerk, or custom OpenID Connect providers are supported.
- Meters, features, and plans are created — At least one plan must be published.
- 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:
Code
Save and deploy. Once the plugin is enabled, ensure:
- Stripe is connected (see Stripe Integration)
- At least one plan is published
Plugin options
Pass options to zuploMonetizationPlugin() in docs/zudoku.config.tsx. All
options are optional.
| Option | Type | Description |
|---|---|---|
pricing.title | string | Heading of the pricing page. Defaults to "Pricing". |
pricing.subtitle | string | Text under the heading. Defaults to "See our pricing options and choose the one that best suits your needs.". |
pricing.units | Record<string, string> | Unit names for usage in plan cards, keyed by rate card or feature key. Defaults to "unit". |
checkout.renderBeforeCheckout | (props) => ReactNode | null | Renders your own step on /checkout before the customer goes to Stripe. See below. |
Code
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:
| Prop | Description |
|---|---|
plan | The plan the customer chose on the pricing page. |
onComplete | Call it after your own submit succeeds to continue to checkout. |
onCancel | Call it to abandon the purchase and return the customer to the pricing page. |
Code
- Returning
nullskips the form and goes straight to checkout. - The
/checkoutroute 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 key | Description |
|---|---|
isCustom | Set to "true" to mark the plan as a contact-sales plan. |
contactUrl | Where the button goes: a URL, an email address, or a portal path such as /contact. |
contactLabel | Button text. Defaults to Contact Sales. |
Code
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.
Checkout links
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:
- Open Account Settings → Custom Domains in the Zuplo Portal
- Add your domain (e.g.,
developers.your-company.com) - Configure the DNS records as instructed
- SSL is provisioned automatically
Your monetization pages, including the Stripe Checkout redirect flow, work seamlessly with custom domains.