zuplo 6.69.10 → 6.70.0

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/plans.mdx

@@ -138,7 +138,6 @@ curl \
           "type": "flat_fee",
           "key": "monthly_fee",
           "name": "Monthly Fee",
-          "featureKey": "monthly_fee",
           "billingCadence": "P1M",
           "price": {
             "type": "flat",

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

@@ -78,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",
@@ -154,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",

package/docs/articles/monetization/stripe-integration.md

@@ -42,7 +42,9 @@ in Stripe at the moment a charge is needed (as invoice line items).
 
 ### Via the Zuplo Portal
 
-1. Navigate to **Services → Monetization Service → Payment Provider**
+1. Open your project's
+   [**Services**](https://portal.zuplo.com/+/account/project/services) page,
+   select the Monetization Service, then go to **Payment Provider**
 2. Click **Configure** on the Stripe card
 3. Enter a **Name** and paste your **Stripe API Key**
 4. Click **Save**
@@ -111,8 +113,10 @@ Intents, Refunds, or Stripe Billing Meters — leave all of those at **None**.
    or `Zuplo Monetization (production)`.
 3. For each of the eight permissions above, set the level shown in the table.
 4. Click **Create key**, copy the value (`rk_test_...` or `rk_live_...`), and
-   paste it into **Services → Monetization Service → Payment Provider** in your
-   Zuplo project.
+   paste it into the Monetization Service's **Payment Provider** screen (open
+   your project's
+   [**Services**](https://portal.zuplo.com/+/account/project/services) page,
+   then the Monetization Service) in your Zuplo project.
 
 :::caution
 
@@ -208,22 +212,22 @@ When a customer cancels through the Developer Portal, the timing of the
 cancellation depends on whether the current phase has billable items:
 
 - **Paid phases** — the portal sends `timing: "next_billing_cycle"`. The
-  subscription is scheduled to cancel at the end of the current billing
-  period, the customer retains access until then, and the API key stops
-  working at period end.
+  subscription is scheduled to cancel at the end of the current billing period,
+  the customer retains access until then, and the API key stops working at
+  period end.
 - **Free phases** — the portal sends `timing: "immediate"`. With nothing to
   invoice at period end, there's no billing period to wait out, so the
   subscription cancels and access is revoked right away. Two situations fall
   into this branch:
-  - The customer is on a **free trial phase** (the first phase of a plan
-    with a later paid phase) and cancels before the trial converts.
-  - The customer is on a **free plan** — a plan whose only phase has no
-    billable rate cards (every rate card's `price` is `null`).
+  - The customer is on a **free trial phase** (the first phase of a plan with a
+    later paid phase) and cancels before the trial converts.
+  - The customer is on a **free plan** — a plan whose only phase has no billable
+    rate cards (every rate card's `price` is `null`).
 
 For programmatic cancellation, see
 [Cancellation](./subscription-lifecycle.md#cancellation) in the Subscription
-Lifecycle guide — the API endpoint accepts a `timing` parameter to control
-this same behavior explicitly.
+Lifecycle guide — the API endpoint accepts a `timing` parameter to control this
+same behavior explicitly.
 
 ## Proration
 

package/docs/articles/monetization/subscription-lifecycle.md

@@ -104,9 +104,9 @@ API is needed.
       "rateCards": [
         {
           "type": "flat_fee",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": null,
           "price": null,
           "entitlementTemplate": {
@@ -124,9 +124,9 @@ API is needed.
       "rateCards": [
         {
           "type": "usage_based",
-          "key": "api_calls",
+          "key": "api_requests",
           "name": "API Calls",
-          "featureKey": "api_calls",
+          "featureKey": "api_requests",
           "billingCadence": "P1M",
           "price": {
             "type": "tiered",

package/docs/articles/monorepo-deployment.mdx

@@ -220,8 +220,7 @@ jobs:
 
 Store your Zuplo API key as a GitHub Actions secret:
 
-1. Go to [portal.zuplo.com](https://portal.zuplo.com) and navigate to your
-   account **Settings** > **API Keys**
+1. In the Zuplo Portal, navigate to your account **Settings** > **API Keys**
 2. Copy the API key
 3. In your GitHub repository, go to **Settings** > **Secrets and variables** >
    **Actions**
@@ -322,7 +321,7 @@ the deployed environment. Timeouts can indicate:
   `routes.oas.json` or `policies.json` exist in the `modules/` directory
 - **Missing environment variables** — If your policies or handlers reference
   environment variables with `$env(VAR_NAME)`, make sure those variables are
-  configured in the Zuplo portal under your project's
+  configured in the Zuplo Portal under your project's
   [environment variables](./environment-variables.mdx)
 
 ### Build succeeds but deploy fails

package/docs/articles/source-control-setup-github.mdx

@@ -18,10 +18,12 @@ new Zuplo project.
 
 1. Connect to GitHub
 
-   Go to your project in the Zuplo portal, click **Settings**, then select
-   **Source Control**. If your project isn't already connected to GitHub click
-   the **Connect to GitHub** button and follow the auth flow. You'll need to
-   grant permissions for any GitHub organizations you want to work with.
+   Open your
+   [project settings](https://portal.zuplo.com/+/account/project/settings/general)
+   in the Zuplo Portal, then select **Source Control**. If your project isn't
+   already connected to GitHub click the **Connect to GitHub** button and follow
+   the auth flow. You'll need to grant permissions for any GitHub organizations
+   you want to work with.
 
    ![Connect GitHub](../../public/media/step-4-deploying-to-the-edge/image-1.png)
 

package/docs/articles/step-1-setup-basic-gateway.mdx

@@ -18,9 +18,9 @@ Note - Zuplo also supports building and running your API locally. To learn more
 
 1. **Sign-in**
 
-   Sign in to [portal.zuplo.com](https://portal.zuplo.com) and create a free
-   account. Create a new **empty** project (don't import an existing project,
-   we'll set up git later). Then...
+   Sign in to the Zuplo Portal and create a free account. Then
+   [create a new empty project](https://portal.zuplo.com/+/account/projects/new)
+   (don't import an existing project, we'll set up git later). Then...
 
 1. Add your first **Route**
 

package/docs/articles/step-3-add-api-key-auth-local.mdx

@@ -102,9 +102,10 @@ Let's get started.
 
 1.  Set up an API Key
 
-    In order to call your API, you need to configure an API consumer. Go to the
-    [Zuplo Portal](https://portal.zuplo.com), then open the project you are
-    working on, **Services**, then click **Configure** on the "API Key Service".
+    In order to call your API, you need to configure an API consumer. In the
+    Zuplo Portal, open the
+    [**Services**](https://portal.zuplo.com/+/account/project/services) tab for
+    your project, then click **Configure** on the "API Key Service".
 
     :::warning