zuplo 6.67.32 → 6.68.0

package/docs/articles/monetization/api-access.mdx

@@ -0,0 +1,69 @@
+---
+title: API Access
+sidebar_label: API Access
+---
+
+:::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.
+
+:::
+
+## Buckets
+
+Each Zuplo project includes three isolated buckets that mirror your
+[environment structure](../environments.mdx):
+
+| Bucket           | Purpose                                                       |
+| ---------------- | ------------------------------------------------------------- |
+| **Working Copy** | Your development sandbox for building and testing             |
+| **Preview**      | Staging environments for validating changes before production |
+| **Production**   | Your live environment serving real customers                  |
+
+Meters, features, plans, and subscriptions are all scoped to a specific bucket.
+This isolation enables independent development workflows where you can:
+
+- **Experiment freely** - Test new pricing models or usage tracking in
+  development without affecting production data
+- **Validate changes** - Promote your product catalog configuration through
+  preview environments before going live
+- **Maintain separation** - Keep development test data completely isolated from
+  production customer usage
+
+When you're satisfied with your configuration in one bucket, you can recreate
+that same configuration in another bucket to promote changes through your
+deployment pipeline.
+
+## Authentication
+
+All Monetization API requests require authentication using a Zuplo API key.
+
+All examples in this documentation assume the following environment variables
+are set in your terminal:
+
+```bash
+# Your Bucket ID (could be working-copy, preview, or production)
+# (Found in Project Services > Bucket Details)
+export BUCKET_ID=your-bucket-id
+# Your Zuplo API Key (Found in Account Settings > Zuplo API Keys)
+export ZAPI_KEY=zpka_YOUR_API_KEY
+```
+
+Include your API key in the `Authorization` header:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/meters \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+## API Reference
+
+For complete API operations, see the API Reference documentation:
+
+- [Meters API](../../api/metering-meters)
+- [Features API](../../api/metering-features)
+- [Plans API](../../api/metering-plans)

package/docs/articles/monetization/billing-models.md

@@ -0,0 +1,520 @@
+---
+title: Billing Models Guide
+sidebar_label: Billing 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.
+
+:::
+
+Zuplo supports four billing models, each targeting different business needs. You
+can mix models on the same pricing page and even within the same plan.
+
+## Fixed monthly quotas
+
+The most common API monetization model. The customer pays a flat monthly price
+and gets a fixed number of requests (or other metered units). When the quota is
+exhausted, the API returns `403 Forbidden` until the next billing period.
+
+**When to use:** Predictable revenue, simple to explain, works for most B2B SaaS
+APIs.
+
+**How customers experience it:** They subscribe, get their API key, and use the
+API until their quota runs out. Clear and predictable for budgeting.
+
+### Example: Three-tier SaaS pricing
+
+**Free tier:**
+
+```json
+{
+  "key": "free",
+  "name": "Free",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "default",
+      "name": "Free",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "flat_fee",
+          "key": "api_calls",
+          "name": "API Calls",
+          "featureKey": "api_calls",
+          "billingCadence": null,
+          "price": null,
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000,
+            "isSoftLimit": false
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Starter — $29/mo, 10,000 requests:**
+
+```json
+{
+  "key": "starter",
+  "name": "Starter",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "default",
+      "name": "Starter Monthly",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "flat_fee",
+          "key": "api_calls",
+          "name": "API Calls",
+          "featureKey": "api_calls",
+          "billingCadence": "P1M",
+          "price": {
+            "type": "flat",
+            "amount": "29.00"
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 10000,
+            "isSoftLimit": false
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Pro — $99/mo, 100,000 requests:**
+
+```json
+{
+  "key": "pro",
+  "name": "Pro",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "default",
+      "name": "Pro Monthly",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "flat_fee",
+          "key": "api_calls",
+          "name": "API Calls",
+          "featureKey": "api_calls",
+          "billingCadence": "P1M",
+          "price": {
+            "type": "flat",
+            "amount": "99.00"
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 100000,
+            "isSoftLimit": false
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Stripe behavior:** Subscription created with a fixed-price line item. Payment
+charged in advance at the start of each billing period.
+
+## Pay-as-you-go
+
+:::caution{title="Coming Soon"}
+
+Pay-as-you-go billing 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 pure pay-as-you-go pricing, contact
+[support](mailto:support@zuplo.com) to discuss your use case.
+
+:::
+
+No upfront commitment. The customer provides a credit card, uses the API as much
+as they want, and is billed monthly in arrears for actual usage.
+
+**When to use:** Low barrier to entry, usage-based AI APIs, developer tools
+where usage is unpredictable.
+
+**How customers experience it:** They sign up, add a payment method, and only
+pay for what they use. No quota limits, no hard caps.
+
+### Example: Per-request billing
+
+```json
+{
+  "key": "paygo",
+  "name": "Pay As You Go",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "default",
+      "name": "Usage-Based",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "usage_based",
+          "key": "api_calls",
+          "name": "API Calls",
+          "featureKey": "api_calls",
+          "billingCadence": "P1M",
+          "price": {
+            "type": "unit",
+            "amount": "0.10"
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "isSoftLimit": true
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Setting `isSoftLimit: true` with no `issueAfterReset` means there is no included
+quota and no hard limit — everything is billed per-unit.
+
+### Example: Graduated per-request billing (volume discount)
+
+```json
+{
+  "key": "paygo-graduated",
+  "name": "Pay As You Go",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "default",
+      "name": "Usage-Based",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "usage_based",
+          "key": "api_calls",
+          "name": "API Calls",
+          "featureKey": "api_calls",
+          "billingCadence": "P1M",
+          "price": {
+            "type": "tiered",
+            "mode": "graduated",
+            "tiers": [
+              {
+                "upToAmount": "10000",
+                "unitPrice": { "type": "unit", "amount": "0.10" }
+              },
+              {
+                "upToAmount": "100000",
+                "unitPrice": { "type": "unit", "amount": "0.05" }
+              },
+              {
+                "upToAmount": null,
+                "unitPrice": { "type": "unit", "amount": "0.01" }
+              }
+            ]
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "isSoftLimit": true
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Stripe behavior:** Subscription with usage-based billing. Usage is tracked
+continuously and billed through the integrated billing system at the end of each
+period.
+
+**Risk consideration:** Pay-as-you-go means you're extending credit. If a
+customer racks up significant usage and their card declines at invoicing time,
+you absorb the loss. Consider setting a hard entitlement limit as a spending cap
+if this concerns you.
+
+## Monthly quotas with overages
+
+A hybrid model combining the predictability of fixed quotas with the flexibility
+of usage-based billing. The customer pays a fixed monthly price for a base
+allowance. If they exceed it, overage is billed per-unit in arrears.
+
+**When to use:** Enterprise APIs, weather data services, any API where you want
+guaranteed revenue with upside on heavy usage.
+
+**How customers experience it:** They get a known base cost for budgeting, with
+the ability to burst beyond their quota without service interruption.
+
+### Example: Enterprise API with overage
+
+Overage is modeled as graduated tiered pricing. The first tier covers the
+included allowance at a flat price, and subsequent tiers charge per-unit for
+overage:
+
+```json
+{
+  "key": "enterprise",
+  "name": "Enterprise",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "default",
+      "name": "Enterprise Monthly",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "usage_based",
+          "key": "api_calls",
+          "name": "API Calls",
+          "featureKey": "api_calls",
+          "billingCadence": "P1M",
+          "price": {
+            "type": "tiered",
+            "mode": "graduated",
+            "tiers": [
+              {
+                "upToAmount": "1000000",
+                "flatPrice": { "type": "flat", "amount": "499.00" },
+                "unitPrice": null
+              },
+              {
+                "flatPrice": null,
+                "unitPrice": { "type": "unit", "amount": "0.05" }
+              }
+            ]
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000000,
+            "isSoftLimit": true
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+$499/month for 1,000,000 requests. Requests beyond 1M are billed at $0.05 each.
+A customer using 1,200,000 requests pays $499 + (200,000 x $0.05) = $499 + $100
+= $599.
+
+### Example: Graduated overage pricing
+
+For high-volume APIs, you might want overage pricing that decreases at scale:
+
+```json
+{
+  "key": "enterprise",
+  "name": "Enterprise",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "default",
+      "name": "Enterprise Monthly",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "usage_based",
+          "key": "api_calls",
+          "name": "API Calls",
+          "featureKey": "api_calls",
+          "billingCadence": "P1M",
+          "price": {
+            "type": "tiered",
+            "mode": "graduated",
+            "tiers": [
+              {
+                "upToAmount": "1000000",
+                "flatPrice": { "type": "flat", "amount": "499.00" },
+                "unitPrice": null
+              },
+              {
+                "upToAmount": "5000000",
+                "unitPrice": { "type": "unit", "amount": "0.05" }
+              },
+              {
+                "unitPrice": { "type": "unit", "amount": "0.02" }
+              }
+            ]
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000000,
+            "isSoftLimit": true
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Stripe behavior:** Subscription with both a fixed-price component (advance
+payment) and a usage-based component (arrears). Usage is tracked and billed
+through the integrated billing system.
+
+## Credits / tokens (prepaid)
+
+:::caution{title="Coming Soon"}
+
+Credit/token-based billing is supported by the underlying monetization models,
+but the developer portal experience has not been fully tested for this billing
+model yet. If you need prepaid credit billing, contact
+[sales@zuplo.com](mailto:sales@zuplo.com) to discuss your use case.
+
+:::
+
+Customers buy credit bundles in advance. Each API call (or token, or byte)
+consumes a defined number of credits. When credits are exhausted, service stops
+until the customer tops up.
+
+**When to use:** AI APIs, marketplaces, any service where customers want to buy
+in bulk at a discount and burn down over time.
+
+**How customers experience it:** They buy a credit pack, use the API until
+credits run out, then buy more. No ongoing subscription commitment.
+
+### Example: AI token credit packs
+
+**Small pack:**
+
+```json
+{
+  "key": "credits-small",
+  "name": "50,000 Credits",
+  "currency": "USD",
+  "billingCadence": null,
+  "phases": [
+    {
+      "key": "default",
+      "name": "Credit Pack",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "usage_based",
+          "key": "api_credits",
+          "name": "API Credits",
+          "featureKey": "api_credits",
+          "billingCadence": null,
+          "price": {
+            "type": "package",
+            "amount": "49.00",
+            "quantityPerPackage": 50000
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 50000,
+            "isSoftLimit": false
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Large pack (better per-credit rate):**
+
+```json
+{
+  "key": "credits-large",
+  "name": "500,000 Credits",
+  "currency": "USD",
+  "billingCadence": null,
+  "phases": [
+    {
+      "key": "default",
+      "name": "Credit Pack",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "usage_based",
+          "key": "api_credits",
+          "name": "API Credits",
+          "featureKey": "api_credits",
+          "billingCadence": null,
+          "price": {
+            "type": "package",
+            "amount": "299.00",
+            "quantityPerPackage": 500000
+          },
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 500000,
+            "isSoftLimit": false
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Credit mapping:** Credits are arbitrary units. You define how many credits
+each API operation consumes via the `MonetizationInboundPolicy` meter
+configuration:
+
+```json
+// Simple: 1 credit per request
+{ "meters": { "api_credits": 1 } }
+
+// Weighted: different endpoints consume different credits
+// (configure separate policies per route)
+// /v1/simple-lookup -> 1 credit
+{ "meters": { "api_credits": 1 } }
+// /v1/ai-analysis -> 10 credits
+{ "meters": { "api_credits": 10 } }
+```
+
+**Stripe behavior:** One-time payment for the credit pack. Credit balance is
+tracked internally. Customers can purchase additional packs at any time
+(top-ups).
+
+## Mixing models on one pricing page
+
+You can offer multiple billing models simultaneously. A common pattern:
+
+| Tier         | Model           | Configuration                                             |
+| ------------ | --------------- | --------------------------------------------------------- |
+| Free         | Fixed quota     | 1,000 requests/month, hard limit, no credit card required |
+| Starter      | Fixed quota     | 10,000 requests/month, $29/month, hard limit              |
+| Pro          | Quota + overage | 100,000 requests/month, $99/month, $0.001/request overage |
+| Enterprise   | Pay-as-you-go   | Volume-discounted per-request pricing, custom terms       |
+| Credit Packs | Prepaid credits | Buy 50K/$49, 500K/$299, 5M/$1,999                         |
+
+Each is a separate plan in Zuplo. The Developer Portal displays them together on
+the pricing page, and customers choose the model that fits their usage pattern.
+
+## Choosing the right model
+
+| Factor                          | Fixed Quota   | Pay-as-you-go  | Quota + Overage | Credits          |
+| ------------------------------- | ------------- | -------------- | --------------- | ---------------- |
+| Revenue predictability          | High          | Low            | Medium          | Medium           |
+| Customer budget clarity         | High          | Low            | High            | High             |
+| Barrier to entry                | Medium        | Low            | Medium          | Low              |
+| Revenue upside from heavy users | None          | High           | High            | Medium           |
+| Payment risk                    | Low (advance) | High (arrears) | Medium          | None (prepaid)   |
+| Best for                        | SaaS APIs     | Dev tools, AI  | Enterprise      | AI, marketplaces |