Terminal
Terminal/Skill
Steps for charging for an API with Zuplo, covering meters, plans, Stripe billing, and subscription and usage troubleshooting.
By Zuplo
Works with
npx skills add zuplo/tools --skill zuplo-monetizationSet up usage-based billing and subscription management for your API using Zuplo's built-in monetization product with Stripe integration.
Before configuring monetization features, read the relevant Zuplo documentation. The monetization product is in beta and evolving. Use these sources in priority order:
node_modules/zuplo/docs/articles/monetization/ — version-matched, always available offline. Check both the project root and parent directories for monorepos.search-zuplo-docs and ask-question-about-zuplo if the Zuplo MCP server is connected.https://zuplo.com/docs/articles/monetization/quickstarthttps://zuplo.com/docs/articles/monetization/stripe-integrationhttps://zuplo.com/docs/articles/monetization/developer-portalhttps://zuplo.com/docs/articles/monetization/subscription-lifecyclehttps://zuplo.com/docs/articles/monetization/billing-modelshttps://zuplo.com/docs/articles/monetization/plan-exampleshttps://zuplo.com/docs/policies/monetization-inboundZuplo handles metering, quota enforcement, and subscription state. Stripe handles payment processing, billing, and invoicing.
Developer Portal Zuplo Gateway Stripe
┌─────────────────┐ ┌──────────────┐ ┌─────────┐
│ Pricing page │──Subscribe──> │ Creates sub │──Creates───> │ Checkout│
│ Usage dashboard │ │ Issues API │ subscription │ Payment │
│ Key management │<──Redirect── │ key + quota │<──Confirms── │ Billing │
│ Plan changes │ │ Meters usage │──Reports───> │ Invoice │
└─────────────────┘ └──────────────┘ └─────────┘
The flow:
| Step | What | Details |
|---|---|---|
| 1 | Create project | Use the Zuplo Portal or CLI |
| 2 | Enable monetization plugin | Add to docs/zudoku.config.tsx |
| 3 | Configure Monetization Service | Portal > Services > Monetization Service |
| 4 | Create meters | Define what to measure (API calls, tokens, etc.) |
| 5 | Create features | Link features to meters or define boolean features |
| 6 | Create and publish plans | Set pricing, tiers, entitlements |
| 7 | Connect Stripe | Add Stripe API key in Monetization Service |
| 8 | Add monetization policy | Add to config/policies.json and attach to routes |
| 9 | Deploy and test | Push changes, subscribe, make API calls |
Use a fresh project for monetization setup.
Or via CLI:
npx create-zuplo-api@latest my-monetized-api
In docs/zudoku.config.tsx, add the monetization plugin:
import { zuploMonetizationPlugin } from "@zuplo/zudoku-plugin-monetization";
const config: ZudokuConfig = {
// ... your existing config
plugins: [
zuploMonetizationPlugin(),
// ... any other plugins you have
],
};
Save and wait for deployment to complete.
Meters track what you want to measure (API calls, tokens, data transfer, etc.).
In Monetization Service > Meters > Add Meter > Blank Meter:
| Field | Example value | Description |
|---|---|---|
| Name | API | Display name |
| Event | api | Event type identifier (used in policy config) |
| Description | API Calls | Human-readable description |
| Aggregation | SUM | How to combine values (SUM, COUNT, MAX, etc.) |
| Value Property | $.total | JSONPath to extract value from events |
Features define customer entitlements. In Monetization Service > Features > Add Feature:
Usage-based feature (linked to a meter):
api, Key: api, Linked Meter: APIFlat fee feature (no meter):
Monthly Fee, Key: monthly_fee, Linked Meter: (empty)Boolean feature (on/off capability):
Metadata Support, Key: metadata_support, Linked Meter: (empty)Plans combine features with pricing and entitlements. In Plans > Create Plan.
| Plan | Monthly Fee | Included Requests | Overage Rate | Metadata Support |
|---|---|---|---|---|
| Developer | $9.99 | 1,000 | $0.10/req | No |
| Pro | $19.99 | 5,000 | $0.05/req | Yes |
| Business | $29.99 | 10,000 | $0.01/req | Yes |
Each plan has rate cards for each feature:
Monthly Fee rate card:
Flat feeMonthlyIn advance$9.99)No entitlementAPI usage rate card (tiered with overage):
TieredMonthlyGraduated0 to Last 1000, Unit Price $0, Flat Price $01001 to infinity, Unit Price $0.10, Flat Price $0Metered (track usage)1000enabled (allows overage; disable for hard cap)Boolean feature rate card:
FreeBoolean (on/off)For more plan examples (trials, credits, pay-as-you-go): read node_modules/zuplo/docs/articles/monetization/billing-models.md and plan-examples.mdx
sk_test_...)Always use sk_test_... for development. Switch to sk_live_... for production.
When you publish plans, Zuplo automatically creates corresponding Stripe Products and Prices.
config/policies.json{
"name": "monetization-inbound",
"policyType": "monetization-inbound",
"handler": {
"export": "MonetizationInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"meters": {
"api": 1
}
}
}
}
The meters object maps meter event slugs to units per request. "api": 1 means each request increments the api meter by 1.
config/routes.oas.json"x-zuplo-route": {
"corsPolicy": "none",
"handler": {
"export": "urlForwardHandler",
"module": "$import(@zuplo/runtime)",
"options": {
"baseUrl": "https://your-backend.example.com"
}
},
"policies": {
"inbound": ["monetization-inbound"]
}
}
Important: The MonetizationInboundPolicy handles API key authentication automatically on monetized routes. You do NOT need a separate api-key-inbound policy on routes that have the monetization policy.
| Option | Type | Default | Description |
|---|---|---|---|
meters | object | {} | Maps meter slugs to units per request |
meterOnStatusCodes | string | all | Status code ranges to meter (e.g. "200-299") |
authHeader | string | "authorization" | Header containing the API key |
authScheme | string | "Bearer" | Auth scheme prefix |
cacheTtlSeconds | number | 60 | Cache TTL for monetization lookups |
For advanced metering (dynamic meters at runtime): read node_modules/zuplo/docs/articles/monetization/monetization-policy.md
4242 4242 4242 4242curl --request GET \
--url https://<your-gateway-url>/todos \
--header 'Authorization: Bearer <your-api-key>'
403 Forbidden when quota exceeded (hard limit plans)| State | API Access | Description |
|---|---|---|
active | Yes | Subscription active, payment current |
inactive | No | Not yet active or deactivated |
canceled | No | Subscription canceled |
scheduled | No | Scheduled for future activation |
zuplo_max_payment_overdue_days plan metadata.Subscriptions can also be managed via the Metering API. See node_modules/zuplo/docs/articles/monetization/subscription-lifecycle.md.
Once monetization is enabled, the portal provides:
All of these are in node_modules/zuplo/docs/articles/monetization/:
| Topic | Doc file |
|---|---|
| Dynamic metering at runtime | monetization-policy.md |
| Billing models (flat rate, tiered, pay-as-you-go) | billing-models.md |
| Plan examples (trials, multiple tiers) | plan-examples.mdx |
| Private (invite-only) plans | private-plans.md |
| Tax collection with Stripe Tax | tax-collection.md |
| Subscription lifecycle and API | subscription-lifecycle.md |
| Troubleshooting | troubleshooting.md |
| Problem | Cause | Fix |
|---|---|---|
| Pricing page not showing | Plugin not added or not deployed | Add zuploMonetizationPlugin() to zudoku.config.tsx and redeploy |
| Plans not visible on pricing page | Plans not published | Publish each plan via ... > Publish Plan |
| API returns 401 on monetized route | No API key or invalid key | Get key from Developer Portal subscription |
| API returns 403 on monetized route | Quota exceeded (hard limit) | Upgrade plan or wait for quota reset |
| Usage not tracking | Meter slug mismatch | Ensure meters key in policy matches the meter event slug exactly |
| Stripe not connected | API key not configured | Configure Stripe in Monetization Service > Payment Provider |
| Subscription not created after checkout | Deployment not complete | Ensure latest code is deployed before testing |
node_modules/zuplo/docs/articles/monetization/ — full monetization documentationhttps://zuplo.com/docs/articles/monetizationsetup-monetization.sh script automates meter, feature, plan creation, and Stripe connection via the API