zuplo 6.67.32 → 6.68.0

package/docs/articles/monetization/plans.mdx

@@ -0,0 +1,266 @@
+---
+title: Plans
+sidebar_label: Plans
+---
+
+:::note{title="Beta"}
+
+API Monetization is in beta and free to try. The APIs are stable but should be
+evaluated in non-production environments first. To go to production, contact
+[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
+announced.
+
+:::
+
+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:
+
+<Diagram height="h-96">
+  <DiagramNode id="plan">Plan</DiagramNode>
+  <DiagramNode id="phase">Phase</DiagramNode>
+  <DiagramNode id="ratecard">Rate Card</DiagramNode>
+  <DiagramNode id="price">Price</DiagramNode>
+  <DiagramNode id="entitlement">Entitlement</DiagramNode>
+  <DiagramNode id="feature">Feature</DiagramNode>
+  <DiagramNode id="meter">Meter</DiagramNode>
+  <DiagramEdge from="plan" to="phase" />
+  <DiagramEdge from="phase" to="ratecard" />
+  <DiagramEdge from="ratecard" to="price" />
+  <DiagramEdge from="ratecard" to="entitlement" />
+  <DiagramEdge from="entitlement" to="feature" />
+  <DiagramEdge from="feature" to="meter" />
+</Diagram>
+
+| Entity          | Description                                           |
+| --------------- | ----------------------------------------------------- |
+| **Plan**        | A subscription tier (e.g., Pro, Enterprise)           |
+| **Phase**       | A time period within a plan (e.g., trial, default)    |
+| **Rate Card**   | Pricing and entitlements for a feature within a phase |
+| **Price**       | The pricing model (flat, tiered, package, etc.)       |
+| **Entitlement** | Usage limits and access controls for customers        |
+| **Feature**     | A capability that can be metered or toggled           |
+| **Meter**       | Tracks usage data for metered features                |
+
+Plans contain **phases**, and each phase contains **rate cards** that define
+pricing and entitlements. See [Rate Cards](./rate-cards.mdx) for details on
+configuring pricing within plans.
+
+:::note
+
+Before creating a plan, you must first define the [Features](./features.mdx)
+that will be included. Plans reference features by their `key`, so features must
+exist before they can be added to rate cards.
+
+:::
+
+## 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 default phase with $99/month subscription and 10,000 included API calls
+- Overage pricing at $0.01 per additional call
+- Static features for premium access
+
+For step-by-step examples building plans from simple to complex, see
+[Plan Examples](./plan-examples.mdx).
+
+```shell
+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": "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": { "type": "flat", "amount": "99.00" },
+                "unitPrice": null
+              },
+              {
+                "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
+
+| Phase   | Duration | API Requests       | Cost      |
+| ------- | -------- | ------------------ | --------- |
+| Trial   | 1 week   | 1,000 (hard limit) | Free      |
+| Default | Ongoing  | 10,000 included    | $99/month |
+
+After the trial ends, customers automatically move to the default phase. In the
+default phase, the first 10,000 API requests are included in the $99 monthly
+fee. Additional requests are billed at $0.01 each (soft limit allows overage).
+
+## Plan Properties
+
+| Property          | Required | Description                                                   |
+| ----------------- | -------- | ------------------------------------------------------------- |
+| `key`             | Yes      | Unique identifier for the plan                                |
+| `name`            | Yes      | Human-readable display name                                   |
+| `currency`        | Yes      | Three-letter ISO currency code (e.g., `USD`)                  |
+| `billingCadence`  | Yes      | Billing period as ISO 8601 duration (e.g., `P1M` for monthly) |
+| `phases`          | Yes      | Array of plan phases with rate cards                          |
+| `description`     | No       | Detailed description of the plan                              |
+| `metadata`        | No       | Custom key-value pairs for your own use                       |
+| `proRatingConfig` | No       | Proration settings (see below)                                |
+
+## Phase Properties
+
+| Property    | Required | Description                                                           |
+| ----------- | -------- | --------------------------------------------------------------------- |
+| `key`       | Yes      | Unique identifier for the phase within the plan                       |
+| `name`      | Yes      | Human-readable display name                                           |
+| `duration`  | No       | ISO 8601 duration (e.g., `P1W` for 1 week). Omit for the final phase. |
+| `rateCards` | Yes      | Array of rate cards defining pricing and entitlements                 |
+
+## Proration
+
+Plans support automatic proration when customers upgrade or downgrade
+mid-billing-period. Enable proration with the `proRatingConfig` property:
+
+```json
+{
+  "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
+
+:::caution
+
+Plans must be published before customers can subscribe to them. A newly created
+plan starts in `draft` status and is not available for subscriptions until
+published.
+
+:::
+
+Transition a draft plan to active status:
+
+```shell
+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
+
+| Duration | Description |
+| -------- | ----------- |
+| `P1W`    | Weekly      |
+| `P1M`    | Monthly     |
+| `P3M`    | Quarterly   |
+| `P1Y`    | Yearly      |
+
+## API Reference
+
+For complete API operations (list, get, update, delete, archive), see the
+[Plans API Reference](../../api/metering-plans).

package/docs/articles/monetization/pricing-models.mdx

@@ -0,0 +1,225 @@
+---
+title: Pricing Models
+sidebar_label: Pricing Models
+---
+
+:::note{title="Beta"}
+
+API Monetization is in beta and free to try. The APIs are stable but should be
+evaluated in non-production environments first. To go to production, contact
+[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
+announced.
+
+:::
+
+Pricing models define how charges are calculated within a
+[rate card](./rate-cards.mdx). Each model suits different business scenarios,
+from simple flat fees to complex usage-based pricing.
+
+## Flat Fee Pricing
+
+Flat fee pricing charges a fixed amount regardless of usage. Use `flat_fee` rate
+cards for subscriptions, setup fees, or access charges.
+
+### Recurring Subscription
+
+A monthly platform fee that recurs each billing period:
+
+```json
+{
+  "type": "flat_fee",
+  "key": "platform_fee",
+  "name": "Platform Fee",
+  "billingCadence": "P1M",
+  "price": {
+    "type": "flat",
+    "amount": "99.00"
+  }
+}
+```
+
+### One-Time Setup Fee
+
+A setup fee charged once when the subscription starts (no `billingCadence`):
+
+```json
+{
+  "type": "flat_fee",
+  "key": "setup_fee",
+  "name": "Setup Fee",
+  "price": {
+    "type": "flat",
+    "amount": "500.00"
+  }
+}
+```
+
+## Per-Unit Pricing
+
+Per-unit pricing charges a fixed amount for each unit of metered usage. Use
+`usage_based` rate cards linked to a feature.
+
+```json
+{
+  "type": "usage_based",
+  "featureKey": "api_calls",
+  "billingCadence": "P1M",
+  "price": {
+    "type": "unit",
+    "amount": "0.001"
+  },
+  "entitlementTemplate": {
+    "type": "metered",
+    "isSoftLimit": true
+  }
+}
+```
+
+**Example:** At $0.001 per unit, a customer using 100,000 API calls pays:
+
+`100,000 × $0.001 = $100`
+
+## Tiered Pricing
+
+Tiered pricing varies the price based on usage volume. There are two modes:
+
+### Graduated Pricing
+
+Each unit is charged according to the tier it falls into:
+
+```json
+{
+  "type": "usage_based",
+  "featureKey": "api_calls",
+  "billingCadence": "P1M",
+  "price": {
+    "type": "tiered",
+    "mode": "graduated",
+    "tiers": [
+      { "upToAmount": 1000, "unitPrice": { "amount": "0.10" } },
+      { "upToAmount": 10000, "unitPrice": { "amount": "0.05" } },
+      { "upToAmount": null, "unitPrice": { "amount": "0.01" } }
+    ]
+  },
+  "entitlementTemplate": {
+    "type": "metered",
+    "isSoftLimit": true
+  }
+}
+```
+
+| Tier | Units          | Unit Price |
+| ---- | -------------- | ---------- |
+| 1    | 0 - 1,000      | $0.10      |
+| 2    | 1,001 - 10,000 | $0.05      |
+| 3    | 10,001+        | $0.01      |
+
+**Example:** A customer using 15,000 units pays:
+
+`(1,000 × $0.10) + (9,000 × $0.05) + (5,000 × $0.01) = $100 + $450 + $50 = $600`
+
+### Volume Pricing
+
+All units are charged at the rate of the highest tier reached:
+
+```json
+{
+  "type": "usage_based",
+  "featureKey": "api_calls",
+  "billingCadence": "P1M",
+  "price": {
+    "type": "tiered",
+    "mode": "volume",
+    "tiers": [
+      { "upToAmount": 1000, "unitPrice": { "amount": "0.10" } },
+      { "upToAmount": 10000, "unitPrice": { "amount": "0.05" } },
+      { "upToAmount": null, "unitPrice": { "amount": "0.01" } }
+    ]
+  },
+  "entitlementTemplate": {
+    "type": "metered",
+    "isSoftLimit": true
+  }
+}
+```
+
+**Example:** A customer using 15,000 units pays:
+
+`15,000 × $0.01 = $150`
+
+All units are charged at the tier 3 rate because usage exceeded 10,000.
+
+### Included Usage with Overage
+
+Combine a flat fee for included usage with per-unit overage charges. This is a
+common pattern for "X calls included, then $Y per additional call":
+
+```json
+{
+  "type": "usage_based",
+  "featureKey": "api_calls",
+  "billingCadence": "P1M",
+  "price": {
+    "type": "tiered",
+    "mode": "graduated",
+    "tiers": [
+      { "upToAmount": 10000, "flatPrice": { "amount": "0" } },
+      { "upToAmount": null, "unitPrice": { "amount": "0.01" } }
+    ]
+  },
+  "entitlementTemplate": {
+    "type": "metered",
+    "issueAfterReset": 10000,
+    "isSoftLimit": true
+  }
+}
+```
+
+This grants 10,000 API calls included (via `issueAfterReset`), then charges
+$0.01 per additional call.
+
+## Package Pricing
+
+Package pricing sells usage in fixed bundles rather than individual units:
+
+```json
+{
+  "type": "usage_based",
+  "featureKey": "api_calls",
+  "billingCadence": "P1M",
+  "price": {
+    "type": "package",
+    "amount": "10.00",
+    "quantityPerPackage": 1000
+  },
+  "entitlementTemplate": {
+    "type": "metered",
+    "isSoftLimit": true
+  }
+}
+```
+
+| Usage | Packages | Total |
+| ----- | -------- | ----- |
+| 0     | 0        | $0    |
+| 500   | 1        | $10   |
+| 1,000 | 1        | $10   |
+| 1,001 | 2        | $20   |
+| 5,500 | 6        | $60   |
+
+Usage is rounded up to the next package.
+
+## Choosing a Pricing Model
+
+| Model         | Best For                                                  |
+| ------------- | --------------------------------------------------------- |
+| **Flat**      | Subscriptions, setup fees, fixed-price features           |
+| **Per-Unit**  | Simple usage billing where each unit has equal value      |
+| **Graduated** | Volume discounts while maintaining revenue on lower tiers |
+| **Volume**    | Aggressive volume discounts to incentivize high usage     |
+| **Package**   | Simplified billing, encouraging bulk purchases            |
+
+## Complete Example
+
+See [Plan Examples](./plan-examples.mdx) for step-by-step examples showing how
+to build plans with different pricing models.

package/docs/articles/monetization/private-plans.md

@@ -0,0 +1,154 @@
+---
+title: Private Plans — Invite-Only Subscriptions
+sidebar_label: Private Plans
+---
+
+:::note{title="Beta"}
+
+API Monetization is in beta and free to try. The APIs are stable but should be
+evaluated in non-production environments first. To go to production, contact
+[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
+announced.
+
+:::
+
+Private plans are hidden from the public pricing table and can only be accessed
+by users you explicitly invite. Use private plans for custom enterprise pricing,
+partner deals, or beta testing with specific users.
+
+## Prerequisites
+
+Before creating private plans, complete the [Quickstart](./quickstart.md) guide
+to set up meters, features, and at least one public plan.
+
+## Create a private plan
+
+A plan becomes private when you set `"zuplo_private_plan": "true"` in the plan's
+`metadata` field. You can create private plans through the API.
+
+This example creates an invite-only Developer plan with 1,000 included requests
+and $0.10/request overage:
+
+```bash
+curl -X POST "https://dev.zuplo.com/v3/metering/${ZUPLO_BUCKET_ID}/plans" \
+  -H "Authorization: Bearer ${ZUPLO_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "billingCadence": "P1M",
+    "currency": "USD",
+    "description": "1000 requests per month with overages",
+    "key": "private_developer",
+    "metadata": {
+      "zuplo_private_plan": "true"
+    },
+    "name": "Private Developer",
+    "proRatingConfig": {
+      "enabled": true,
+      "mode": "max_consumption_based"
+    },
+    "phases": [
+      {
+        "duration": null,
+        "key": "default",
+        "name": "Default",
+        "rateCards": [
+          {
+            "billingCadence": "P1M",
+            "featureKey": "monthly_fee",
+            "key": "monthly_fee",
+            "name": "Monthly Fee",
+            "price": {
+              "amount": "9.99",
+              "paymentTerm": "in_advance",
+              "type": "flat"
+            },
+            "type": "flat_fee"
+          },
+          {
+            "billingCadence": "P1M",
+            "entitlementTemplate": {
+              "isSoftLimit": true,
+              "issueAfterReset": 1000,
+              "preserveOverageAtReset": false,
+              "type": "metered",
+              "usagePeriod": "P1M"
+            },
+            "featureKey": "api",
+            "key": "api",
+            "name": "api",
+            "price": {
+              "mode": "graduated",
+              "tiers": [
+                {
+                  "flatPrice": {
+                    "amount": "0",
+                    "type": "flat"
+                  },
+                  "unitPrice": null,
+                  "upToAmount": "155000"
+                },
+                {
+                  "flatPrice": null,
+                  "unitPrice": {
+                    "amount": "0.10",
+                    "type": "unit"
+                  }
+                }
+              ],
+              "type": "tiered"
+            },
+            "type": "usage_based"
+          }
+        ]
+      }
+    ]
+  }'
+```
+
+Save the returned `id` — you need it to publish and invite users.
+
+The key difference from a public plan is `metadata.zuplo_private_plan` set to
+`"true"`. Everything else (rate cards, entitlements, pricing) works the same as
+public plans.
+
+## Publish the plan
+
+Like standard plans, private plans are created as drafts. Publish before users
+can subscribe:
+
+```bash
+curl -X POST "https://dev.zuplo.com/v3/metering/${ZUPLO_BUCKET_ID}/plans/${PLAN_ID}/publish" \
+  -H "Authorization: Bearer ${ZUPLO_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+## Invite a user
+
+After publishing, create an invite tied to the user's email address. The user
+does not need to exist in Zuplo yet, but they must sign in with the invited
+email to see the private plan.
+
+```bash
+curl -X POST "https://dev.zuplo.com/v3/metering/${ZUPLO_BUCKET_ID}/plan-invites" \
+  -H "Authorization: Bearer ${ZUPLO_API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "email": "user@example.com",
+    "planId": "${PLAN_ID}"
+  }'
+```
+
+Once the invite is created, the invited user sees this plan on the Developer
+Portal pricing page after logging in. Users who have not been invited do not see
+the plan.
+
+## How it works
+
+- Private plans do not appear on the public pricing table.
+- Only users with a matching invite (by email) see the plan after signing in.
+- A user can be invited to multiple private plans.
+- Private plans support the same rate cards, entitlements, and billing features
+  as public plans.
+- Subscriptions to private plans work identically to public plan subscriptions
+  (Stripe Checkout, API key provisioning, usage tracking).