Going to Production with Monetization

You have built out your monetization configuration in Stripe test mode and your customers are ready to pay real money. This guide covers:

• The pre-production checklist — items to verify before enabling real charges
• Billing model readiness — which pricing models are production-ready today
• Stripe live-mode cutover — step-by-step instructions to connect live payments
• Beta limitations — constraints to design around before launch

Before you start

Going to production with monetization requires coordination with the Zuplo team. The monetization feature is currently in public beta — the APIs are stable and the core billing flows work end-to-end, but production pricing for the monetization feature itself has not yet been announced.

The Zuplo team will confirm your configuration, walk you through any beta-specific considerations for your use case, and enable your production bucket for live billing.

Pre-production checklist

Work through each item before enabling real charges. The summary table lists every check; the sections below give the detail and links.

Authentication provider verified

Your Developer Portal must have an authentication provider configured so that customers can sign in, subscribe, and manage their API keys. Verify that your auth provider (Auth0, Clerk, or a custom OpenID Connect provider) works correctly across all environments — working copy, preview, and production.

See Developer Portal Setup → Prerequisites for details.

Meters, features, and plans configured

Confirm that your production bucket has the same meters, features, and plans you tested in your working-copy or preview bucket. Monetization configuration is scoped per-bucket, so you must recreate it in production — it does not automatically promote between environments.

Key checks:

• Meter keys match policy configuration. The meter slug/eventType, the feature key, and the meters map in your MonetizationInboundPolicy must all use the same key. See Meters → Naming Consistency.
• Plans are published. Draft plans are not visible to customers. Publish each plan from the Monetization Service in the Zuplo Portal.
• Currency is correct. Plans support any ISO 4217 currency code (USD, EUR, AUD, GBP, etc.). Verify the currency field on every plan — you cannot change it after customers subscribe.
• Plan ordering is set. The monetization configuration planOrder array controls both the pricing page display order and upgrade/downgrade logic. Make sure it reflects your intended tier hierarchy.

Stripe live-mode connected

Your production environment must use a Stripe live key (sk_live_* or rk_live_*). Test keys and live keys are completely separate environments in Stripe — customers, invoices, and payment methods created in test mode do not exist in live mode.

Billing profile configured

Every bucket that processes payments needs a default billing profile. The billing profile is created automatically when you connect Stripe, but you should verify:

Check billing readiness programmatically:

Code
curl "https://dev.zuplo.com/v3/metering/$BUCKET_ID/billing-readiness" \
  -H "Authorization: Bearer $ZAPI_KEY"

The response confirms whether Stripe is connected and a default billing profile exists.

Webhook endpoint validated

When you connect Stripe, Zuplo registers a webhook endpoint automatically so it can react to payment events (successful charges, failed payments, disputes). Verify the webhook is healthy:

If the webhook is missing or unhealthy, disconnect and reconnect Stripe from the Monetization Service's Payment Provider screen in the Zuplo Portal.

Quota behavior chosen and tested

Each metered entitlement can enforce a hard limit or a soft limit:

Test both paths in your working-copy environment before going live:

See Rate Cards for how isSoftLimit and issueAfterReset interact, and Monetization Policy Reference for how the gateway enforces limits.

Subscription lifecycle tested

Before real money is on the line, walk through every lifecycle state:

See Subscription Lifecycle for the full details on each state transition.

Payment grace period configured

The default grace period for overdue payments is 3 days. During this window, customers retain API access while Stripe retries the charge. After the grace period, access is blocked.

You can customize the grace period at three levels. Higher precedence overrides lower:

Set the value to 0 to block access immediately when payment fails.

Billing models in production

Not all billing models have the same level of portal support today. Choose the right model for your launch based on current readiness.

Fixed monthly quotas — production-ready

The most common and most stable model. Customers pay a flat monthly price for an included number of requests. When the quota is exhausted, the API returns 403 Forbidden (hard limit) or bills overages (soft limit).

This model is fully supported in the Developer Portal pricing table, checkout flow, usage dashboard, and invoicing.

See Billing Models → Fixed monthly quotas for configuration examples.

Monthly quotas with overages — production-ready

A hybrid model where customers pay a base price for an included allowance, with per-unit overage billing in arrears for usage above the limit. This is modeled using graduated tiered pricing with isSoftLimit: true.

Fully supported end-to-end. See Billing Models → Monthly quotas with overages for examples.

Pay-as-you-go — limited portal support

Pure pay-as-you-go billing (no upfront cost, bill entirely in arrears for actual usage) is supported by the underlying monetization models, but the Developer Portal pricing table experience has not been fully tested for this billing model yet.

If you need pay-as-you-go pricing in production, contact support@zuplo.com to discuss your use case and current workarounds.

See Billing Models → Pay-as-you-go for the data model and configuration.

Credits / tokens (prepaid) — limited portal support

Credit/token-based billing is supported by the underlying data model, but the Developer Portal experience has not been fully tested for this billing model.

If you need prepaid credit billing, contact sales@zuplo.com to discuss your use case.

See Billing Models → Credits / tokens for configuration examples.

How usage metering works with Stripe

A common point of confusion: Zuplo does not use Stripe Billing Meters, Stripe Subscriptions, Stripe Products, or Stripe Prices. Zuplo manages plans, subscriptions, metering, and entitlements internally. Stripe is used only for money — collecting payments and issuing invoices.

The flow works like this:

1. Every API request that hits a monetized route is metered in real time by the MonetizationInboundPolicy.
2. Usage events are aggregated internally by Zuplo — they are not sent to Stripe as individual events.
3. At the end of each billing period, Zuplo calculates the total usage, applies the plan's pricing model (flat fee, tiered, per-unit, etc.), and creates a Stripe Invoice with the appropriate line items.
4. Stripe collects payment from the customer's saved payment method.

This means you will not see usage events, billing meters, or subscription objects in your Stripe dashboard. You will see Customers and Invoices. To check usage and subscription state, use the Zuplo metering API or the Developer Portal's usage dashboard.

Code
curl -X POST "https://dev.zuplo.com/v3/metering/$BUCKET_ID/meters/api_requests/query" \
  -H "Authorization: Bearer $ZAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filterSubscription": ["SUBSCRIPTION_ID"],
    "from": "2026-05-01T00:00:00Z",
    "to": "2026-05-31T23:59:59Z",
    "windowSize": "DAY"
  }'

Connecting Stripe live mode

When your test configuration is validated and you are ready to accept real payments, follow these steps to connect your production environment to Stripe live mode.

Step 1: Create a Stripe restricted key for production

Step 2: Connect to your production environment

Step 3: Recreate your monetization configuration

Because monetization configuration is scoped per-bucket, you need to set up meters, features, plans, and the monetization configuration in your production bucket. You can do this through the Portal UI or via the monetization APIs.

Step 4: Verify with a real charge

Step 5: Monitor first production transactions

After going live, keep a close eye on:

Known beta limitations

The following limitations apply during the beta period. Design around them when planning your production launch. As noted in Before you start, production access requires coordination with the Zuplo sales team, and production pricing for the monetization feature has not yet been announced.

Zuplo plan requirements for monetization

Monetization is available during beta on all Zuplo plan tiers, including Free and Builder. However, production workloads typically need capabilities that exceed what the Free and Builder tiers offer.

There is currently no self-serve plan between Builder and Enterprise. If you need capabilities beyond Builder but are not ready for a full Enterprise engagement, email sales@zuplo.com to discuss your options.

For current plan details and pricing, see the Zuplo pricing page.

Getting help when going live

What to include in your request

To help the team resolve your issue quickly, include:

Next steps

Once you have completed the checklist, connected Stripe live mode, and verified your first real charge, your monetized API is in production. Monitor your Stripe Dashboard webhooks and invoices closely during the first billing cycle.

• Troubleshooting — common issues and debugging tools
• Subscription Lifecycle — managing ongoing upgrades, downgrades, and cancellations
• Billing Models Guide — exploring additional pricing strategies as your business grows