This guide walks through progressively building a plan, starting simple and
adding complexity. All examples assume you have already created:
A meter called api_requests that tracks API calls
A feature called api_requests linked to that meter
1. Basic Fixed Monthly Plan
A simple plan with a flat $9.99/month fee and 1,000 API requests included.
curl \ https://dev.zuplo.com/v3/metering/ $BUCKET_ID /plans \ --request POST \ --header "Authorization: Bearer $ZAPI_KEY " \ --header "Content-Type: application/json" \ --data @- << EOF { "key": "starter", "name": "Starter Plan", "description": "1,000 API requests per month", "currency": "USD", "billingCadence": "P1M", "phases": [ { "key": "default", "name": "Default", "duration": null, "rateCards": [ { "type": "flat_fee", "key": "api_requests", "name": "API Requests", "featureKey": "api_requests", "billingCadence": "P1M", "price": { "type": "flat", "amount": "9.99" }, "entitlementTemplate": { "type": "metered", "issueAfterReset": 1000, "isSoftLimit": false, "usagePeriod": "P1M" } } ] } ] } EOF
What this does:
Charges $9.99 at the start of each month
Grants 1,000 API requests per month
Hard limit (isSoftLimit: false) - requests are blocked after 1,000
2. Add a Free Trial
Building on the previous example, add a 2-week free trial with 1,000 requests.
curl \ https://dev.zuplo.com/v3/metering/ $BUCKET_ID /plans \ --request POST \ --header "Authorization: Bearer $ZAPI_KEY " \ --header "Content-Type: application/json" \ --data @- << EOF { "key": "starter", "name": "Starter Plan", "description": "1,000 API requests per month with 2-week free trial", "currency": "USD", "billingCadence": "P1M", "phases": [ { "key": "trial", "name": "Free Trial", "duration": "P2W", "rateCards": [ { "type": "flat_fee", "key": "api_requests", "name": "API Requests (Trial)", "featureKey": "api_requests", "billingCadence": null, "price": null, "entitlementTemplate": { "type": "metered", "issueAfterReset": 1000, "isSoftLimit": false, "usagePeriod": "P2W" } } ] }, { "key": "default", "name": "Default", "duration": null, "rateCards": [ { "type": "flat_fee", "key": "api_requests", "name": "API Requests", "featureKey": "api_requests", "billingCadence": "P1M", "price": { "type": "flat", "amount": "9.99" }, "entitlementTemplate": { "type": "metered", "issueAfterReset": 1000, "isSoftLimit": false, "usagePeriod": "P1M" } } ] } ] } EOF
What changed:
Added a trial phase with duration: "P2W" (2 weeks)
Trial phase has price: null and billingCadence: null - it's free
After 2 weeks, customer automatically moves to the default phase
3. Add Overage Charges
Now allow customers to exceed their quota and charge $0.01 per additional
request after the first 1,000.
curl \ https://dev.zuplo.com/v3/metering/ $BUCKET_ID /plans \ --request POST \ --header "Authorization: Bearer $ZAPI_KEY " \ --header "Content-Type: application/json" \ --data @- << EOF { "key": "starter", "name": "Starter Plan", "description": "1,000 API requests per month with 2-week free trial and overages", "currency": "USD", "billingCadence": "P1M", "phases": [ { "key": "trial", "name": "Free Trial", "duration": "P2W", "rateCards": [ { "type": "flat_fee", "key": "api_requests", "name": "API Requests (Trial)", "featureKey": "api_requests", "billingCadence": null, "price": null, "entitlementTemplate": { "type": "metered", "issueAfterReset": 1000, "isSoftLimit": false, "usagePeriod": "P2W" } } ] }, { "key": "default", "name": "Default", "duration": null, "rateCards": [ { "type": "flat_fee", "key": "subscription_fee", "name": "Starter Plan Subscription", "billingCadence": "P1M", "price": { "type": "flat", "amount": "9.99", "paymentTerm": "in_advance" } }, { "type": "usage_based", "key": "api_requests", "name": "API Requests", "featureKey": "api_requests", "billingCadence": "P1M", "entitlementTemplate": { "type": "metered", "issueAfterReset": 1000, "isSoftLimit": true, "usagePeriod": "P1M" }, "price": { "type": "tiered", "mode": "graduated", "tiers": [ { "upToAmount": "1000", "flatPrice": { "type": "flat", "amount": "0.00" }, "unitPrice": null }, { "flatPrice": null, "unitPrice": { "type": "unit", "amount": "0.01" } } ] } } ] } ] } EOF
What changed:
Split the default phase into two rate cards: a billing-only flat_fee rate
card (no featureKey, paymentTerm: "in_advance") that collects the $9.99
subscription fee at the start of each billing period, and a usage_based rate
card that grants the entitlement and prices overage
Tier 1's flatPrice is set to $0 because the $9.99 is now collected by the
separate flat_fee rate card — leaving it at $9.99 here would double-charge
the customer in arrears at the end of the period
Changed isSoftLimit to true so requests continue past 1,000 and tier 2
applies — overage is billed at $0.01 per request above the allowance, in
arrears at the end of the period
Example billing:
Usage Base Fee Overage Total 500 $9.99 $0 $9.99 1,000 $9.99 $0 $9.99 1,500 $9.99 500 × $0.01 = $5 $14.99 5,000 $9.99 4,000 × $0.01 = $40 $49.99
4. Add Static Entitlements
Finally, add a static entitlement for "large payloads" that grants premium
features without metering.
Before adding the large_payloads rate card, you must first create a feature
with key: "large_payloads".
curl \ https://dev.zuplo.com/v3/metering/ $BUCKET_ID /plans \ --request POST \ --header "Authorization: Bearer $ZAPI_KEY " \ --header "Content-Type: application/json" \ --data @- << EOF { "key": "starter", "name": "Starter Plan", "description": "1,000 API requests per month with 2-week free trial and overages", "currency": "USD", "billingCadence": "P1M", "phases": [ { "key": "trial", "name": "Free Trial", "duration": "P2W", "rateCards": [ { "type": "flat_fee", "key": "api_requests", "name": "API Requests (Trial)", "featureKey": "api_requests", "billingCadence": null, "price": null, "entitlementTemplate": { "type": "metered", "issueAfterReset": 1000, "isSoftLimit": false, "usagePeriod": "P2W" } }, { "type": "flat_fee", "key": "large_payloads", "name": "Large Payloads (Trial)", "featureKey": "large_payloads", "billingCadence": null, "price": null, "entitlementTemplate": { "type": "boolean", "config": true } } ] }, { "key": "default", "name": "Default", "duration": null, "rateCards": [ { "type": "flat_fee", "key": "subscription_fee", "name": "Starter Plan Subscription", "billingCadence": "P1M", "price": { "type": "flat", "amount": "9.99", "paymentTerm": "in_advance" } }, { "type": "usage_based", "key": "api_requests", "name": "API Requests", "featureKey": "api_requests", "billingCadence": "P1M", "entitlementTemplate": { "type": "metered", "issueAfterReset": 1000, "isSoftLimit": true, "usagePeriod": "P1M" }, "price": { "type": "tiered", "mode": "graduated", "tiers": [ { "upToAmount": "1000", "flatPrice": { "type": "flat", "amount": "0.00" }, "unitPrice": null }, { "flatPrice": null, "unitPrice": { "type": "unit", "amount": "0.01" } } ] } }, { "type": "flat_fee", "key": "large_payloads", "name": "Large Payloads", "featureKey": "large_payloads", "billingCadence": null, "price": null, "entitlementTemplate": { "type": "boolean", "config": true } } ] } ] } EOF
What changed:
Added large_payloads rate card to both phases
Uses type: "boolean" with config: true to grant the feature
No meter required - this is a static on/off entitlement
Final plan summary:
Phase Duration API Requests Large Payloads Cost Trial 2 weeks 1,000 (hard limit) Enabled Free Default Ongoing 1,000 + overages Enabled $9.99/month
Last modified on May 24, 2026
