Copy page

Concepts

Plans

Plans are subscription tiers that package features together. They represent the rows on your pricing page - Free, Pro, Enterprise - each with different feature access and usage limits. Plans define what customers get when they subscribe.

Plan Structure

Plans follow a hierarchical structure where each level defines a specific aspect of your pricing:

Plans contain phases, and each phase contains rate cards that define pricing and entitlements. See Rate Cards for details on configuring pricing within plans.

Plan Lifecycle

Plans move through a defined lifecycle:

1. Draft - Initial state when created. Can be modified freely.
2. Active - Published and available for subscriptions. Cannot be modified.
3. Archived - No longer available for new subscriptions but existing subscriptions continue.

Example: Pro Plan with Trial

This example creates a Pro plan with:

• A 1-week free trial phase with 1,000 API calls
• A subscription_fee flat-fee rate card on the default phase that charges $99 in advance at the start of each billing period
• A usage_based rate card with 10,000 included API requests per billing period and $0.01 per request overage in arrears
• A priority_support static feature granted on both phases

For step-by-step examples building plans from simple to complex, see Plan Examples.

Code
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": "pro",
  "name": "Pro Plan",
  "description": "For growing teams with a 1-week free trial",
  "currency": "USD",
  "billingCadence": "P1M",
  "phases": [
    {
      "key": "trial",
      "name": "Trial",
      "duration": "P1W",
      "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": "P1W"
          }
        },
        {
          "type": "flat_fee",
          "key": "priority_support",
          "name": "Priority Support (Trial)",
          "featureKey": "priority_support",
          "billingCadence": null,
          "price": null,
          "entitlementTemplate": {
            "type": "boolean",
            "config": true
          }
        }
      ]
    },
    {
      "key": "default",
      "name": "Default",
      "duration": null,
      "rateCards": [
        {
          "type": "flat_fee",
          "key": "subscription_fee",
          "name": "Subscription Fee",
          "billingCadence": "P1M",
          "price": {
            "type": "flat",
            "amount": "99.00",
            "paymentTerm": "in_advance"
          }
        },
        {
          "type": "usage_based",
          "key": "api_requests",
          "name": "API Requests",
          "featureKey": "api_requests",
          "billingCadence": "P1M",
          "entitlementTemplate": {
            "type": "metered",
            "issueAfterReset": 10000,
            "isSoftLimit": true,
            "usagePeriod": "P1M"
          },
          "price": {
            "type": "tiered",
            "mode": "graduated",
            "tiers": [
              {
                "upToAmount": "10000",
                "flatPrice": null,
                "unitPrice": { "type": "unit", "amount": "0.00" }
              },
              {
                "flatPrice": null,
                "unitPrice": { "type": "unit", "amount": "0.01" }
              }
            ]
          }
        },
        {
          "type": "flat_fee",
          "key": "priority_support",
          "name": "Priority Support",
          "featureKey": "priority_support",
          "billingCadence": null,
          "price": null,
          "entitlementTemplate": {
            "type": "boolean",
            "config": true
          }
        }
      ]
    }
  ]
}
EOF

How This Plan Works

After the trial ends, customers automatically move to the default phase. The $99 monthly subscription fee is charged in advance at the start of each billing period via the subscription_fee flat-fee rate card. The plan includes 10,000 API requests per period; additional requests are billed at $0.01 each in arrears (soft limit allows overage).

Plan Properties

Phase Properties

Proration

Plans support automatic proration when customers upgrade or downgrade mid-billing-period. Enable proration with the proRatingConfig property:

Code
{
  "proRatingConfig": {
    "enabled": true,
    "mode": "max_consumption_based"
  }
}

When proration is enabled, charges are automatically adjusted based on the portion of the billing period remaining at the time of the plan change.

Publishing a Plan

Transition a draft plan to active status:

Code
curl \
  https://dev.zuplo.com/v3/metering/$BUCKET_ID/plans/$PLAN_ID/publish \
  --request POST \
  --header "Authorization: Bearer $ZAPI_KEY"

Once published, a plan cannot be modified. To make changes, you must create a new version of the plan.

Common Billing Cadences

API Reference

For complete API operations (list, get, update, delete, archive), see the Plans API Reference.