zuplo 6.69.9 → 6.69.11

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

@@ -46,9 +46,10 @@ are set in your terminal:
 
 ```bash
 # Your Bucket ID (could be working-copy, preview, or production)
-# (Found in Project Services > Bucket Details)
+# (Found in Project Services > Bucket Details — https://portal.zuplo.com/+/account/project/services)
 export BUCKET_ID=your-bucket-id
-# Your Zuplo API Key (Found in Account Settings > Zuplo API Keys)
+# Your Zuplo API Key (Found in Account Settings > Zuplo API Keys —
+# https://portal.zuplo.com/+/account/settings/api-keys)
 export ZAPI_KEY=zpka_YOUR_API_KEY
 ```
 

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

@@ -45,15 +45,16 @@ API until their quota runs out. Clear and predictable for budgeting.
       "rateCards": [
         {
           "type": "flat_fee",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": null,
           "price": null,
           "entitlementTemplate": {
             "type": "metered",
             "issueAfterReset": 1000,
-            "isSoftLimit": false
+            "isSoftLimit": false,
+            "usagePeriod": "P1M"
           }
         }
       ]
@@ -78,9 +79,9 @@ API until their quota runs out. Clear and predictable for budgeting.
       "rateCards": [
         {
           "type": "flat_fee",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": "P1M",
           "price": {
             "type": "flat",
@@ -114,9 +115,9 @@ API until their quota runs out. Clear and predictable for budgeting.
       "rateCards": [
         {
           "type": "flat_fee",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": "P1M",
           "price": {
             "type": "flat",
@@ -134,8 +135,9 @@ API until their quota runs out. Clear and predictable for budgeting.
 }
 ```
 
-**Stripe behavior:** Subscription created with a fixed-price line item. Payment
-charged in advance at the start of each billing period.
+**Stripe behavior:** At the start of each billing period, Zuplo issues a Stripe
+Invoice with a single fixed-price line item; Stripe collects the payment in
+advance.
 
 ## Pay-as-you-go
 
@@ -173,9 +175,9 @@ pay for what they use. No quota limits, no hard caps.
       "rateCards": [
         {
           "type": "usage_based",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": "P1M",
           "price": {
             "type": "unit",
@@ -199,7 +201,7 @@ quota and no hard limit — everything is billed per-unit.
 
 ```json
 {
-  "key": "paygo-graduated",
+  "key": "paygograduated",
   "name": "Pay As You Go",
   "currency": "USD",
   "billingCadence": "P1M",
@@ -211,9 +213,9 @@ quota and no hard limit — everything is billed per-unit.
       "rateCards": [
         {
           "type": "usage_based",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": "P1M",
           "price": {
             "type": "tiered",
@@ -221,14 +223,16 @@ quota and no hard limit — everything is billed per-unit.
             "tiers": [
               {
                 "upToAmount": "10000",
+                "flatPrice": null,
                 "unitPrice": { "type": "unit", "amount": "0.10" }
               },
               {
                 "upToAmount": "100000",
+                "flatPrice": null,
                 "unitPrice": { "type": "unit", "amount": "0.05" }
               },
               {
-                "upToAmount": null,
+                "flatPrice": null,
                 "unitPrice": { "type": "unit", "amount": "0.01" }
               }
             ]
@@ -244,9 +248,8 @@ quota and no hard limit — everything is billed per-unit.
 }
 ```
 
-**Stripe behavior:** Subscription with usage-based billing. Usage is tracked
-continuously and billed through the integrated billing system at the end of each
-period.
+**Stripe behavior:** At the end of each billing period, Zuplo issues a Stripe
+Invoice with usage-based line items in arrears; Stripe collects the payment.
 
 **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,
@@ -285,9 +288,9 @@ overage:
       "rateCards": [
         {
           "type": "usage_based",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": "P1M",
           "price": {
             "type": "tiered",
@@ -300,7 +303,7 @@ overage:
               },
               {
                 "flatPrice": null,
-                "unitPrice": { "type": "unit", "amount": "0.05" }
+                "unitPrice": { "type": "unit", "amount": "0.0005" }
               }
             ]
           },
@@ -316,9 +319,20 @@ overage:
 }
 ```
 
-$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.
+$499 covers up to 1,000,000 requests. Requests beyond 1M are billed at $0.0005
+each. A customer using 1,200,000 requests pays $499 + (200,000 x $0.0005) =
+$499 + $100 = $599.
+
+:::note
+
+The $499 sits inside tier 1's `flatPrice`, not as a separate subscription fee.
+It's charged unconditionally for the period (regardless of actual usage), but
+**in arrears** — it appears on the invoice issued after the end of the billing
+period, as part of the invoice's tiered usage line. To collect $499 at the
+**start** of every billing period instead (a true in-advance subscription fee),
+see [Example: Base fee in advance](#example-base-fee-in-advance) below.
+
+:::
 
 ### Example: Graduated overage pricing
 
@@ -338,9 +352,9 @@ For high-volume APIs, you might want overage pricing that decreases at scale:
       "rateCards": [
         {
           "type": "usage_based",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": "P1M",
           "price": {
             "type": "tiered",
@@ -353,10 +367,10 @@ For high-volume APIs, you might want overage pricing that decreases at scale:
               },
               {
                 "upToAmount": "5000000",
-                "unitPrice": { "type": "unit", "amount": "0.05" }
+                "unitPrice": { "type": "unit", "amount": "0.0005" }
               },
               {
-                "unitPrice": { "type": "unit", "amount": "0.02" }
+                "unitPrice": { "type": "unit", "amount": "0.0002" }
               }
             ]
           },
@@ -372,9 +386,101 @@ For high-volume APIs, you might want overage pricing that decreases at scale:
 }
 ```
 
-**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.
+:::note
+
+Like the previous example, the $499 sits inside tier 1's `flatPrice` and is
+charged unconditionally for the period in arrears, as part of the invoice's
+tiered usage line.
+
+:::
+
+### Example: Base fee in advance
+
+If you need the $499 collected unconditionally at the start of every billing
+period (a true subscription fee), split it into a separate `flat_fee` rate card
+with `paymentTerm: "in_advance"` and set the usage-based rate card's tier 1 to
+$0 per unit for the included quota:
+
+```json
+{
+  "key": "enterprise",
+  "name": "Enterprise",
+  "currency": "USD",
+  "billingCadence": "P1M",
+  "phases": [
+    {
+      "key": "default",
+      "name": "Enterprise Monthly",
+      "duration": null,
+      "rateCards": [
+        {
+          "type": "flat_fee",
+          "key": "subscription_fee",
+          "name": "Enterprise Subscription",
+          "billingCadence": "P1M",
+          "price": {
+            "type": "flat",
+            "amount": "499.00",
+            "paymentTerm": "in_advance"
+          }
+        },
+        {
+          "type": "usage_based",
+          "key": "api_requests",
+          "name": "API Calls",
+          "featureKey": "api_requests",
+          "billingCadence": "P1M",
+          "entitlementTemplate": {
+            "type": "metered",
+            "issueAfterReset": 1000000,
+            "isSoftLimit": true
+          },
+          "price": {
+            "type": "tiered",
+            "mode": "graduated",
+            "tiers": [
+              {
+                "upToAmount": "1000000",
+                "flatPrice": null,
+                "unitPrice": { "type": "unit", "amount": "0.00" }
+              },
+              {
+                "flatPrice": null,
+                "unitPrice": { "type": "unit", "amount": "0.0005" }
+              }
+            ]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Both patterns charge the customer $499 for every billing period regardless of
+usage. The differences are timing and how the fee appears on the invoice:
+
+| Behavior                 | Tier-1 flat price (previous examples)                | Separate flat-fee rate card (this example)                                         |
+| ------------------------ | ---------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| When the $499 is charged | End of period, in arrears                            | Start of period, in advance                                                        |
+| Invoice presentation     | Single tiered usage line item that includes the $499 | Distinct line items: one for the $499, one for usage                               |
+| Best for                 | When end-of-period billing is acceptable             | True subscriptions where the fee should be collected upfront and listed separately |
+
+The `subscription_fee` rate card has no `featureKey` — it's a
+[rate card without a feature](./rate-cards.mdx#rate-cards-without-features), the
+right shape for a billing-only line item that doesn't grant any entitlement.
+
+**Stripe behavior:** At the start of each billing period, Zuplo issues a single
+Stripe Invoice that includes both:
+
+- The $499 fixed-price line item from the `subscription_fee` rate card, charged
+  in advance for the period that's just starting.
+- Any usage-based line items for overage above 1M from the **previous** billing
+  period, charged in arrears.
+
+Stripe collects payment for the full invoice. The first billing period's invoice
+contains only the $499, since there's no prior period to bill overage for. No
+Stripe Subscription is created.
 
 ## Credits / tokens (prepaid)
 

package/docs/articles/monetization/developer-portal.md

@@ -76,8 +76,10 @@ Save and deploy. Once the plugin is enabled, ensure:
 
 ### Plan display order
 
-Control plan display order in the Zuplo Portal under **Services →
-Monetization**. Plans can be reordered using drag-and-drop.
+Control plan display order from your project's
+[**Services**](https://portal.zuplo.com/+/account/project/services) page in the
+Zuplo Portal — open the Monetization Service. Plans can be reordered using
+drag-and-drop.
 
 ### Feature comparison matrix
 
@@ -158,7 +160,9 @@ use the same fonts, colors, and layout as the rest of your portal.
 The Developer Portal runs at `https://your-project.zuplo.dev/docs` by default.
 For production, configure a custom domain:
 
-1. Navigate to **Settings → Custom Domains** in the Zuplo Portal
+1. Open
+   [**Account Settings → Custom Domains**](https://portal.zuplo.com/+/account/settings/custom-domains)
+   in the Zuplo Portal
 2. Add your domain (e.g., `developers.your-company.com`)
 3. Configure the DNS records as instructed
 4. SSL is provisioned automatically

package/docs/articles/monetization/features.mdx

@@ -95,34 +95,6 @@ curl \
 EOF
 ```
 
-### Creating a Billing-Only Feature
-
-Some plans charge a flat subscription fee that isn't tied to any entitlement — a
-monthly access fee, a setup fee, or a fixed retainer. Model these the same way
-as a static feature (no `meterSlug`), then attach them to a plan via a
-`flat_fee` rate card with no `entitlementTemplate` and a price whose
-`paymentTerm` is `"in_advance"`. Zuplo issues a Stripe Invoice for the fee at
-the start of each billing period.
-
-```shell
-curl \
-  https://dev.zuplo.com/v3/metering/$BUCKET_ID/features \
-  --request POST \
-  --header "Authorization: Bearer $ZAPI_KEY" \
-  --header "Content-Type: application/json" \
-  --data @- << EOF
-{
-  "key": "monthly_fee",
-  "name": "Monthly Fee"
-}
-EOF
-```
-
-Because the rate card carries no entitlement, the developer portal's
-feature-comparison matrix doesn't render a row for the feature — the price rolls
-into the plan's headline cost. See the Pro plan example in [Plans](./plans.mdx)
-for the rate-card shape.
-
 ## API Reference
 
 For complete API operations (list, get, archive), see the

package/docs/articles/monetization/meters.mdx

@@ -43,8 +43,10 @@ Track the total number of API requests:
 }
 ```
 
-Each event contains the `subscription` ID linking it to a subscription and a
-`total` field in `data` with the quantity to record:
+Each event identifies the subscription being metered, the actor that drove the
+consumption, and how much to record. The `subscription` field carries the
+subscription ID, the `subject` field identifies the actor, and `data.total`
+carries the quantity:
 
 ```json
 {
@@ -52,7 +54,7 @@ Each event contains the `subscription` ID linking it to a subscription and a
   "specversion": "1.0",
   "type": "api_requests",
   "source": "monetization-policy",
-  "subject": "01KNVXHQG356VA7T7W0V9N21GH",
+  "subject": "acme-prod",
   "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
   "data": {
     "total": 1
@@ -62,8 +64,13 @@ Each event contains the `subscription` ID linking it to a subscription and a
 
 :::note
 
-Events emitted by the `MonetizationInboundPolicy` always set `subject` and
-`subscription` to the same subscription ULID. See
+`subject` identifies _who_ consumed the subscription's entitlements on this
+request — typically the API key's consumer name, the end-user id, or another
+stable per-actor identifier. It is **not** the subscription id (use the
+`subscription` field for that) and is not used to route billing. Its purpose is
+to let you break down usage within a subscription so you can see which key,
+user, or agent drove the consumption — a single subscription will commonly emit
+events with many different `subject` values. See
 [Monetization Policy](./monetization-policy.md) for how usage is recorded.
 
 :::
@@ -96,7 +103,7 @@ consumed 50 tokens looks like this:
   "specversion": "1.0",
   "type": "tokens",
   "source": "monetization-policy",
-  "subject": "01KNVXHQG356VA7T7W0V9N21GH",
+  "subject": "acme-prod",
   "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
   "data": {
     "total": 50
@@ -126,7 +133,7 @@ Each event reports the number of bytes transferred:
   "specversion": "1.0",
   "type": "data_transfer",
   "source": "monetization-policy",
-  "subject": "01KNVXHQG356VA7T7W0V9N21GH",
+  "subject": "acme-prod",
   "subscription": "01KNVXHQG356VA7T7W0V9N21GH",
   "data": {
     "total": 4096

package/docs/articles/monetization/plans.mdx

@@ -138,7 +138,6 @@ curl \
           "type": "flat_fee",
           "key": "monthly_fee",
           "name": "Monthly Fee",
-          "featureKey": "monthly_fee",
           "billingCadence": "P1M",
           "price": {
             "type": "flat",
@@ -204,8 +203,7 @@ 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 `monthly_fee` flat-fee rate card. The plan includes 10,000 API
 requests per period; additional requests are billed at $0.01 each in arrears
-(the soft limit on the metered entitlement allows overage to flow through to the
-next invoice).
+(soft limit allows overage).
 
 ## Plan Properties
 

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

@@ -23,7 +23,8 @@ cards for subscriptions, setup fees, or access charges.
 
 ### Recurring Subscription
 
-A monthly platform fee that recurs each billing period:
+A monthly subscription fee that recurs each billing period and is collected in
+advance:
 
 ```json
 {
@@ -33,11 +34,24 @@ A monthly platform fee that recurs each billing period:
   "billingCadence": "P1M",
   "price": {
     "type": "flat",
-    "amount": "99.00"
+    "amount": "99.00",
+    "paymentTerm": "in_advance"
   }
 }
 ```
 
+Each billing period — every month for `P1M` — Zuplo adds a $99.00 line item for
+this rate card to the customer's Stripe Invoice. Because `paymentTerm` is
+`in_advance` (the default for flat prices), the customer is charged at the start
+of the period rather than the end.
+
+The rate card's `billingCadence` must align with the plan's `billingCadence` —
+see [Rate Cards → Billing Cadence](./rate-cards.mdx#billing-cadence) for the
+alignment rule. A flat-fee rate card like this one doesn't need a `featureKey`
+(see
+[Rate Cards Without Features](./rate-cards.mdx#rate-cards-without-features)) —
+the rate card's `key` and `name` appear directly on the customer's invoice.
+
 ### One-Time Setup Fee
 
 A setup fee charged once when the subscription starts (no `billingCadence`):
@@ -62,7 +76,7 @@ Per-unit pricing charges a fixed amount for each unit of metered usage. Use
 ```json
 {
   "type": "usage_based",
-  "featureKey": "api_calls",
+  "featureKey": "api_requests",
   "billingCadence": "P1M",
   "price": {
     "type": "unit",
@@ -90,7 +104,7 @@ Each unit is charged according to the tier it falls into:
 ```json
 {
   "type": "usage_based",
-  "featureKey": "api_calls",
+  "featureKey": "api_requests",
   "billingCadence": "P1M",
   "price": {
     "type": "tiered",
@@ -125,7 +139,7 @@ All units are charged at the rate of the highest tier reached:
 ```json
 {
   "type": "usage_based",
-  "featureKey": "api_calls",
+  "featureKey": "api_requests",
   "billingCadence": "P1M",
   "price": {
     "type": "tiered",
@@ -157,7 +171,7 @@ common pattern for "X calls included, then $Y per additional call":
 ```json
 {
   "type": "usage_based",
-  "featureKey": "api_calls",
+  "featureKey": "api_requests",
   "billingCadence": "P1M",
   "price": {
     "type": "tiered",
@@ -185,7 +199,7 @@ Package pricing sells usage in fixed bundles rather than individual units:
 ```json
 {
   "type": "usage_based",
-  "featureKey": "api_calls",
+  "featureKey": "api_requests",
   "billingCadence": "P1M",
   "price": {
     "type": "package",

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

@@ -54,7 +54,6 @@ curl -X POST "https://dev.zuplo.com/v3/metering/${ZUPLO_BUCKET_ID}/plans" \
         "rateCards": [
           {
             "billingCadence": "P1M",
-            "featureKey": "monthly_fee",
             "key": "monthly_fee",
             "name": "Monthly Fee",
             "price": {

package/docs/articles/monetization/quickstart.md

@@ -46,7 +46,8 @@ keeps your existing work safe from any breaking changes.
 :::
 
 1. Go to [portal.zuplo.com](https://portal.zuplo.com) and sign in.
-2. Click **New Project** in the top right corner.
+2. Click **New Project** in the top right corner
+   ([open](https://portal.zuplo.com/+/account/projects/new)).
 3. Enter a **Project name** or use the randomly chosen name Zuplo provides.
 4. Select **Starter Project (Recommended)** — it comes with endpoints ready to
    monetize.
@@ -83,7 +84,8 @@ Add the monetization plugin to your Developer Portal configuration.
 
 ## Step 3: Configure the Monetization Service
 
-1. Navigate to the **Services** tab in your project.
+1. Open the [**Services**](https://portal.zuplo.com/+/account/project/services)
+   tab in your project.
 2. Select the environment you want to configure. We will use **Working Copy**
    for this quickstart.
 3. Click **Configure** on the **Monetization Service** card.

package/docs/articles/monetization/rate-cards.mdx

@@ -26,7 +26,9 @@ A rate card consists of:
 - **Feature** - Optional link to a feature from your product catalog
 - **Price** - How much to charge (see [Pricing Models](./pricing-models.mdx))
 - **Entitlement** - Optional usage limits or access controls
-- **Billing Cadence** - How often to bill (monthly, one-time, etc.)
+- **Billing Cadence** - How often this rate card produces a charge — distinct
+  from the plan's billing cadence, and constrained to align with it (see
+  [Billing Cadence](#billing-cadence) below)
 
 ## Rate Card Types
 
@@ -53,8 +55,9 @@ recurring fee. Use these for:
 }
 ```
 
-When `billingCadence` is set (e.g., `P1M` for monthly), the fee recurs each
-billing period. When `billingCadence` is `null`, the fee is charged once per
+When `billingCadence` is set (e.g., `P1M`), the flat fee recurs at that cadence
+— see [Billing Cadence](#billing-cadence) for the constraint relative to the
+plan's cadence. When `billingCadence` is `null`, the fee is charged once per
 subscription phase.
 
 The `paymentTerm` field controls when the charge is collected:
@@ -75,9 +78,9 @@ feature linked to a meter. Use these for:
 ```json
 {
   "type": "usage_based",
-  "key": "api_calls",
+  "key": "api_requests",
   "name": "API Calls",
-  "featureKey": "api_calls",
+  "featureKey": "api_requests",
   "billingCadence": "P1M",
   "price": {
     "type": "unit",
@@ -90,6 +93,36 @@ Usage-based rate cards support multiple pricing models. See
 [Pricing Models](./pricing-models.mdx) for details on unit, tiered, package, and
 dynamic pricing.
 
+## Billing Cadence
+
+A rate card's `billingCadence` controls how often this specific rate card
+produces a charge. It's distinct from the **plan's** `billingCadence`, which
+sets the overall invoice schedule for the subscription:
+
+- For **flat-fee** rate cards, the cadence determines how often the flat fee
+  recurs. Set it to `null` to charge once per subscription phase (a setup fee,
+  onboarding charge, or other one-time payment).
+- For **usage-based** rate cards, the cadence is required and determines the
+  period over which metered usage is aggregated and emitted as an invoice line.
+
+### Alignment with the plan
+
+The rate card's cadence must align with the plan's `billingCadence`. Two
+cadences align when:
+
+- They are identical (e.g., plan `P1M` and rate card `P1M`), or
+- The shorter one divides the longer one without remainder (e.g., plan `P1M`
+  with a rate card at `P3M`, or plan `P1Y` with a rate card at `P1M`).
+
+Plans accept these `billingCadence` values: `PT1H`, `P1D`, `P1W`, `P2W`, `P4W`,
+`P1M`, `P3M`, `P6M`, `P12M`, `P1Y`. A rate card with a cadence that doesn't
+align (for example, `P2M` on a `P3M` plan, where neither divides the other) is
+rejected at plan creation.
+
+This rule exists for invoice-generation correctness: it guarantees that every
+rate-card cycle ends on a plan-invoice boundary, so a single charge from this
+rate card lands on exactly one customer invoice rather than straddling two.
+
 ## Rate Cards With Features
 
 When a rate card is linked to a feature via `featureKey`:
@@ -121,9 +154,9 @@ include:
 ```json
 {
   "type": "usage_based",
-  "key": "api_calls",
+  "key": "api_requests",
   "name": "API Calls",
-  "featureKey": "api_calls",
+  "featureKey": "api_requests",
   "billingCadence": "P1M",
   "price": {
     "type": "unit",