zuplo 6.70.16 → 6.70.22

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

@@ -479,8 +479,7 @@ Stripe Invoice that includes both:
   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.
+contains only the $499, since there's no prior period to bill overage for.
 
 ## Credits / tokens (prepaid)
 
@@ -509,10 +508,10 @@ credits run out, then buy more. No ongoing subscription commitment.
 
 ```json
 {
-  "key": "credits-small",
+  "key": "credits_small",
   "name": "50,000 Credits",
   "currency": "USD",
-  "billingCadence": null,
+  "billingCadence": "P1M",
   "phases": [
     {
       "key": "default",
@@ -520,20 +519,15 @@ credits run out, then buy more. No ongoing subscription commitment.
       "duration": null,
       "rateCards": [
         {
-          "type": "usage_based",
-          "key": "api_credits",
-          "name": "API Credits",
-          "featureKey": "api_credits",
+          "type": "flat_fee",
+          "key": "api_requests",
+          "name": "50,000 API Credits",
+          "featureKey": "api_requests",
           "billingCadence": null,
           "price": {
-            "type": "package",
+            "type": "flat",
             "amount": "49.00",
-            "quantityPerPackage": 50000
-          },
-          "entitlementTemplate": {
-            "type": "metered",
-            "issueAfterReset": 50000,
-            "isSoftLimit": false
+            "paymentTerm": "in_advance"
           }
         }
       ]
@@ -546,10 +540,10 @@ credits run out, then buy more. No ongoing subscription commitment.
 
 ```json
 {
-  "key": "credits-large",
+  "key": "credits_large",
   "name": "500,000 Credits",
   "currency": "USD",
-  "billingCadence": null,
+  "billingCadence": "P1M",
   "phases": [
     {
       "key": "default",
@@ -557,20 +551,15 @@ credits run out, then buy more. No ongoing subscription commitment.
       "duration": null,
       "rateCards": [
         {
-          "type": "usage_based",
-          "key": "api_credits",
-          "name": "API Credits",
-          "featureKey": "api_credits",
+          "type": "flat_fee",
+          "key": "api_requests",
+          "name": "500,000 API Credits",
+          "featureKey": "api_requests",
           "billingCadence": null,
           "price": {
-            "type": "package",
+            "type": "flat",
             "amount": "299.00",
-            "quantityPerPackage": 500000
-          },
-          "entitlementTemplate": {
-            "type": "metered",
-            "issueAfterReset": 500000,
-            "isSoftLimit": false
+            "paymentTerm": "in_advance"
           }
         }
       ]

package/docs/articles/monetization/monetization-policy.md

@@ -296,20 +296,22 @@ the RFC 7807 Problem Details format:
 
 Common error details:
 
-| Condition                       | `detail` message                                                    |
-| ------------------------------- | ------------------------------------------------------------------- |
-| No auth header                  | `"No Authorization Header"`                                         |
-| Wrong auth scheme               | `"Invalid Authorization Scheme"`                                    |
-| Empty key after the auth scheme | `"No key present"`                                                  |
-| Cached invalid key or 401       | `"Authorization Failed"`                                            |
-| Invalid API key                 | `"API Key is invalid or does not have access to the API"`           |
-| Expired API key                 | `"API Key has expired."`                                            |
-| Expired subscription            | `"API Key has an expired subscription."`                            |
-| Subscription has no payment     | `"Subscription payment status is not available."`                   |
-| Payment not made                | `"Payment has not been made."`                                      |
-| Payment overdue                 | `"Payment is overdue. Please update your payment method."`          |
-| Quota exhausted                 | `"API Key has exceeded the allowed limit for \"X\" meter."`         |
-| Meter not in subscription       | `"API Key does not have \"X\" meter provided by the subscription."` |
+| Condition                        | `detail` message                                                    |
+| -------------------------------- | ------------------------------------------------------------------- |
+| No auth header                   | `"No Authorization Header"`                                         |
+| Wrong auth scheme                | `"Invalid Authorization Scheme"`                                    |
+| Empty key after the auth scheme  | `"No key present"`                                                  |
+| Cached invalid key or 401        | `"Authorization Failed"`                                            |
+| Invalid API key                  | `"API Key is invalid or does not have access to the API"`           |
+| Expired API key                  | `"API Key has expired."`                                            |
+| Expired subscription             | `"API Key has an expired subscription."`                            |
+| Subscription has no payment      | `"Subscription payment status is not available."`                   |
+| Payment not made                 | `"Payment has not been made."`                                      |
+| Payment overdue                  | `"Payment is overdue. Please update your payment method."`          |
+| Subscription has no entitlements | `"Subscription entitlements are not available."`                    |
+| Meter not in subscription        | `"API Key does not have \"X\" meter provided by the subscription."` |
+| Quota exhausted                  | `"API Key has exceeded the allowed limit for \"X\" meter."`         |
+| Meter access denied              | `"API Key does not have access to \"X\" meter."`                    |
 
 ## Pipeline ordering
 

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

@@ -46,7 +46,7 @@ in Stripe at the moment a charge is needed (as invoice line items).
    [**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**
+3. Paste your **Stripe API Key**
 4. Click **Save**
 
 :::tip
@@ -229,13 +229,6 @@ For programmatic cancellation, see
 Lifecycle guide — the API endpoint accepts a `timing` parameter to control this
 same behavior explicitly.
 
-## Proration
-
-When customers upgrade or downgrade mid-billing-period, charges are prorated
-automatically. Upgrades are charged the prorated difference for the remainder of
-the billing period. Downgrades result in a prorated credit applied to the next
-invoice.
-
 ## Usage-based billing
 
 For plans with usage-based pricing (per-unit, tiered, pay-as-you-go), usage is
@@ -278,8 +271,7 @@ To enable the Stripe Customer Portal:
 
 1. Configure the Customer Portal in your
    [Stripe Dashboard → Settings → Billing → Customer Portal](https://dashboard.stripe.com/settings/billing/portal)
-2. Enable the features you want (update payment method, view invoices, cancel
-   subscription)
+2. Enable the features you want (update payment method, view invoices)
 3. The Developer Portal automatically includes a "Manage Billing" link that
    opens the Stripe Customer Portal
 

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

@@ -17,20 +17,38 @@ trials, upgrades, downgrades, cancellation, and reactivation.
 
 ## Subscription states
 
-| Status      | API access | Description                                       |
-| ----------- | ---------- | ------------------------------------------------- |
-| `active`    | Yes        | Subscription is active and payment is current     |
-| `inactive`  | No         | Subscription is not yet active or was deactivated |
-| `canceled`  | No         | Subscription has been canceled                    |
-| `scheduled` | No         | Subscription is scheduled for future activation   |
+A subscription's lifecycle status is computed from its `activeFrom`/`activeTo`
+window — it is not a stored field, and transitions happen automatically as time
+passes. The four possible values reflect lifecycle only; payment status is
+tracked separately (see the note below).
+
+| Status      | API access | Description                                                         |
+| ----------- | ---------- | ------------------------------------------------------------------- |
+| `active`    | Yes        | Currently in effect with no scheduled end                           |
+| `canceled`  | Yes        | Scheduled to end at a future date; access continues until that date |
+| `inactive`  | No         | Has ended, or was canceled before becoming active                   |
+| `scheduled` | No         | Has not yet started — `activeFrom` is in the future                 |
+
+When a customer cancels a subscription with `next_billing_cycle` timing, its
+status flips from `active` to `canceled` immediately (with `activeTo` set to the
+period end). The customer keeps access throughout the `canceled` window, and the
+status transitions to `inactive` once `activeTo` passes. A subscription in the
+`canceled` state can be reactivated — see [Reactivation](#reactivation) below.
 
 :::note
 
-Access is also governed by payment status. If a payment is overdue beyond the
-grace period (default 3 days), access is blocked even for active subscriptions.
-The grace period is configurable per-customer, per-plan, or per-bucket — see
+Access is also governed by payment status, which is tracked separately. If a
+payment is overdue beyond the grace period (default 3 days), access is blocked
+even for `active` subscriptions. The grace period is configurable per-customer,
+per-plan, or per-bucket — see
 [Subscription and payment validation](./monetization-policy.md#subscription-and-payment-validation).
 
+In the Zuplo admin UI, lifecycle status and payment status are combined into
+derived display labels such as "Access Blocked" or "Payment Failed" to surface
+the effective state at a glance. In the Developer Portal, a subscription with a
+future `activeTo` (whether `active` or `canceled`) is shown with an "Expiring"
+badge and the upcoming end date.
+
 :::
 
 ## Creating subscriptions
@@ -43,8 +61,9 @@ completes Stripe Checkout, and gets their API key immediately.
 1. Customer visits the pricing page
 2. Clicks "Subscribe" on their chosen plan
 3. Completes Stripe Checkout (enters payment details)
-4. Redirected back to the Developer Portal
-5. Subscription is active, API key is generated
+4. Returns to the Developer Portal to review the subscription summary
+5. Clicks "Confirm & Subscribe" to finalize
+6. Subscription is active, API key is generated
 
 ### Programmatic (API)
 
@@ -63,7 +82,7 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions \
 ```
 
 `plan` references the target plan by its `key` (and optionally `version`).
-Provide either `customerId` (the OpenMeter customer ULID, format
+Provide either `customerId` (the metering customer ULID, format
 `^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$`) or `customerKey` (your own
 identifier). Optional fields include `timing` (`"immediate"` by default,
 `"next_billing_cycle"`, or an RFC 3339 timestamp), `startingPhase`, `name`,
@@ -168,23 +187,31 @@ If the plan has a paid phase after the trial:
 - On success: subscription transitions to the paid phase with paid entitlements
 - On failure: access depends on the payment grace period configuration
 
-If the customer cancels during the trial:
+What happens if the customer cancels during the trial depends on whether the
+trial phase has billable rate cards:
 
-- They retain trial access until the trial period ends
-- No payment is charged
-- After the trial period, access is revoked
+- **Free trial** (no priced rate cards in the trial phase, like the example
+  above): access ends immediately, no payment is charged, and the trial does not
+  convert to the paid phase. Cancellation cannot defer to a billing-cycle end
+  because the trial phase has nothing to bill
+- **Paid trial** (the trial phase has a price, e.g., a $1 introductory rate):
+  access continues until the end of the trial period (default
+  `next_billing_cycle` timing), the trial fee is billed on the final invoice,
+  and the trial does not convert to the subsequent paid phase
 
 ## Plan changes (upgrades and downgrades)
 
 ### Customer-initiated (Developer Portal)
 
-Customers can change plans from the Subscriptions page in the Developer Portal:
+Customers can change plans from the **Manage Subscription** section in the
+Developer Portal:
 
-1. Customer clicks "Change Plan" on their active subscription
+1. Customer clicks "Switch Plan" on their active subscription
 2. Sees available plans with pricing comparison
 3. Selects the new plan
 4. Stripe handles proration (charge or credit the difference)
-5. Entitlements update immediately — the customer's quota changes in real time
+5. For an upgrade, new entitlements take effect immediately; for a downgrade,
+   they apply at the next billing cycle
 6. The API key stays the same
 
 ### Programmatic (API)
@@ -203,14 +230,16 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscri
 ```
 
 `timing` accepts `"immediate"`, `"next_billing_cycle"`, or an RFC 3339
-timestamp. To preview the proration credit before committing, call
+timestamp. Optional fields include `startingPhase`, `name`, `description`,
+`metadata`, `alignment`, and `billingAnchor`. To preview the proration credit
+before committing, call
 `POST /v3/metering/{bucketId}/subscriptions/{subscriptionId}/change/estimate-credit`
 with the same body.
 
 ### Proration behavior
 
 When a customer changes plans mid-billing-period, Zuplo uses
-**max-consumption-based proration** to calculate a fair credit from the old
+**max_consumption_based proration** to calculate a fair credit from the old
 plan. Instead of only considering how much time has passed, the system looks at
 both elapsed time and actual quota usage, then uses whichever is greater.
 
@@ -227,8 +256,8 @@ does not reflect their actual usage.
 **Downgrade (e.g., Pro → Starter):**
 
 - New (lower) entitlements take effect at the next billing cycle
-- A proration credit from the old plan is applied as a discount on the next
-  invoice
+- No proration credit is issued. The customer keeps the higher-tier entitlements
+  for the remainder of the current cycle they already paid for.
 
 **Example:** A customer on Starter ($29/month, 10,000 requests) upgrades to Pro
 on day 15 of a 30-day period, having used 7,000 requests.
@@ -240,23 +269,39 @@ on day 15 of a 30-day period, having used 7,000 requests.
 | Max of the two     | 70%            |
 | **Credit applied** | **$8.70**      |
 
-The credit is applied once and is not carried forward to future billing cycles.
+The credit amount is calculated once at the moment of the plan change. It is
+applied as a line-item discount on the next invoice's upfront flat-fee line. If
+the credit exceeds that line's amount, the remainder cascades onto subsequent
+invoices in chronological order until it is fully consumed.
+
+### Quota on plan change
+
+Each subscription tracks its own quota independently. When a customer changes
+plans, a brand-new subscription is created and its entitlement starts measuring
+usage from the switch time — usage from the previous plan does not count against
+the new plan's quota.
 
-### Quota reset on plan change
+Walking through the example above: a customer used 8,000 of their 10,000-request
+Starter quota in the first 15 days. After upgrading to Pro on day 15, the
+customer has the full 50,000-request Pro quota available from day 15 onward,
+regardless of how much was used on Starter. The 8,000 stays attributed to the
+Starter subscription for billing purposes only.
 
-When a customer changes plans, the quota usage counter does **not** reset. If a
-customer used 8,000 of their 10,000-request Starter quota and upgrades to Pro
-(50,000 requests), they have 42,000 remaining for the current period — not
-50,000.
+Gaming via short-lived upgrades is constrained by two other mechanisms:
 
-This prevents gaming where a customer uses up their starter quota, upgrades
-momentarily, and immediately downgrades.
+- Downgrades take effect at the next billing cycle (not immediately), so a
+  customer cannot briefly upgrade and immediately downgrade to grab a fresh
+  quota.
+- Max-consumption-based proration issues zero refund when the old plan's quota
+  was already mostly consumed (see [Proration behavior](#proration-behavior)
+  above), so paying for a short-lived upgrade is not economical.
 
 ## Cancellation
 
 ### Customer-initiated
 
-Customers can cancel from the Developer Portal subscriptions page:
+Customers can cancel from the **Manage Subscription** section in the Developer
+Portal:
 
 1. Customer clicks "Cancel Subscription"
 2. Confirmation dialog explains what happens
@@ -264,6 +309,10 @@ Customers can cancel from the Developer Portal subscriptions page:
 4. Customer retains full access until the period ends
 5. At period end, access is revoked and the API key stops working
 
+For free plans and subscriptions still in their free trial phase, cancellation
+is immediate — there are no billable items left to consume, so end-of-period
+behavior does not apply.
+
 ### Programmatic cancellation
 
 ```bash
@@ -285,11 +334,11 @@ curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscri
 
 ### Cancellation behavior
 
-| Scenario                     | Default behavior                           |
-| ---------------------------- | ------------------------------------------ |
-| Active subscription canceled | Access until period end, then revoked      |
-| Trial subscription canceled  | Access until trial end, no payment charged |
-| Subscription with overage    | Overage billed on final invoice            |
+| Scenario                                 | Default behavior                            |
+| ---------------------------------------- | ------------------------------------------- |
+| Active subscription canceled             | Access until period end, then revoked       |
+| Free trial or free subscription canceled | Access ends immediately, no payment charged |
+| Subscription with overage                | Overage billed on final invoice             |
 
 ## Reactivation
 
@@ -305,14 +354,22 @@ This removes the pending cancellation. The subscription continues as normal. For
 a subscription whose period has already ended, create a new subscription on the
 same plan instead.
 
-## Multiple subscriptions
+## Subscriptions per customer
+
+By default, each customer can hold one active subscription at a time. The
+Developer Portal returns `409 Conflict` ("the maximum number of active
+subscriptions has been reached") when a customer tries to subscribe while
+another subscription is still active or pending cancellation — a subscription in
+the `canceled` wind-down state still counts toward the cap.
 
-A customer can hold multiple active subscriptions simultaneously. This supports
-scenarios like:
+Multi-subscription support is available on request. Contact
+[sales@zuplo.com](mailto:sales@zuplo.com) to enable it for your bucket if you
+need scenarios like:
 
 - A primary monthly subscription plus a credit pack top-up
 - Separate subscriptions for different API products
 - A team subscription and a personal subscription
 
-Each subscription generates its own API key. The customer uses the appropriate
-key for each use case.
+Each subscription is bound to its own consumer record and its own API key, both
+generated when the subscription is created. When a customer holds multiple
+subscriptions, they use the appropriate key for each.

package/docs/cli/ca-certificate-create.mdx

@@ -0,0 +1,76 @@
+---
+title: "Zuplo CLI: Ca Certificate Create"
+sidebar_label: ca-certificate create
+---
+
+<CliCommand
+  command="ca-certificate create"
+  description="Creates a new CA certificate for client mTLS verification"
+  options={[
+  {
+    "name": "name",
+    "type": "string",
+    "description": "The name of the CA certificate (must be a valid JavaScript identifier: starts with a letter, _, or $; contains only letters, digits, _, or $)",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "cert",
+    "type": "string",
+    "description": "Path to a PEM-encoded CA certificate file (.pem, .crt, or .cer with a -----BEGIN CERTIFICATE----- header). DER inputs are not accepted",
+    "required": false,
+    "deprecated": false,
+    "hidden": false,
+    "normalize": true
+  },
+  {
+    "name": "account",
+    "type": "string",
+    "description": "The account name",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "output",
+    "type": "string",
+    "description": "Output format",
+    "default": "default",
+    "required": false,
+    "deprecated": false,
+    "hidden": false,
+    "alias": [
+      "o"
+    ],
+    "choices": [
+      "default",
+      "json"
+    ]
+  }
+]}
+  examples={[
+  [
+    "$0 ca-certificate create --name my_ca --cert ./ca.pem",
+    "Create a CA certificate for client mTLS verification"
+  ],
+  [
+    "$0 ca-certificate create --name my_ca --cert ./ca.pem --output json",
+    "Create a CA certificate and output the result as JSON"
+  ],
+  [
+    "$0 ca-certificate create --name my_ca --cert ./ca.pem --account my-account",
+    "Explicitly specify the account"
+  ]
+]}
+  usage="$0 ca-certificate create --name <name> --cert <file> [options]"
+>
+
+</CliCommand>
+
+## Global options
+
+The following global options are available for all commands:
+
+- [`--help`](./global-options.mdx#help)
+- [`--api-key`](./global-options.mdx#api-key)

package/docs/cli/ca-certificate-delete.mdx

@@ -0,0 +1,67 @@
+---
+title: "Zuplo CLI: Ca Certificate Delete"
+sidebar_label: ca-certificate delete
+---
+
+<CliCommand
+  command="ca-certificate delete"
+  description="Deletes a CA certificate by ID"
+  options={[
+  {
+    "name": "cert-id",
+    "type": "string",
+    "description": "The ID of the CA certificate to delete",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "account",
+    "type": "string",
+    "description": "The account name",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "output",
+    "type": "string",
+    "description": "Output format",
+    "default": "default",
+    "required": false,
+    "deprecated": false,
+    "hidden": false,
+    "alias": [
+      "o"
+    ],
+    "choices": [
+      "default",
+      "json"
+    ]
+  }
+]}
+  examples={[
+  [
+    "$0 ca-certificate delete --cert-id mtlsca_abc123",
+    "Delete a CA certificate"
+  ],
+  [
+    "$0 ca-certificate delete --cert-id mtlsca_abc123 --output json",
+    "Delete a CA certificate and output the result as JSON"
+  ],
+  [
+    "$0 ca-certificate delete --cert-id mtlsca_abc123 --account my-account",
+    "Explicitly specify the account"
+  ]
+]}
+  usage="$0 ca-certificate delete --cert-id <id> [options]"
+>
+
+</CliCommand>
+
+## Global options
+
+The following global options are available for all commands:
+
+- [`--help`](./global-options.mdx#help)
+- [`--api-key`](./global-options.mdx#api-key)

package/docs/cli/ca-certificate-describe.mdx

@@ -0,0 +1,67 @@
+---
+title: "Zuplo CLI: Ca Certificate Describe"
+sidebar_label: ca-certificate describe
+---
+
+<CliCommand
+  command="ca-certificate describe"
+  description="Describes a CA certificate"
+  options={[
+  {
+    "name": "cert-id",
+    "type": "string",
+    "description": "The ID of the CA certificate to describe",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "account",
+    "type": "string",
+    "description": "The account name",
+    "required": false,
+    "deprecated": false,
+    "hidden": false
+  },
+  {
+    "name": "output",
+    "type": "string",
+    "description": "Output format",
+    "default": "default",
+    "required": false,
+    "deprecated": false,
+    "hidden": false,
+    "alias": [
+      "o"
+    ],
+    "choices": [
+      "default",
+      "json"
+    ]
+  }
+]}
+  examples={[
+  [
+    "$0 ca-certificate describe --cert-id mtlsca_abc123",
+    "Get details about a CA certificate"
+  ],
+  [
+    "$0 ca-certificate describe --cert-id mtlsca_abc123 --output json",
+    "Get details as JSON"
+  ],
+  [
+    "$0 ca-certificate describe --cert-id mtlsca_abc123 --account my-account",
+    "Explicitly specify the account"
+  ]
+]}
+  usage="$0 ca-certificate describe --cert-id <id> [options]"
+>
+
+</CliCommand>
+
+## Global options
+
+The following global options are available for all commands:
+
+- [`--help`](./global-options.mdx#help)
+- [`--api-key`](./global-options.mdx#api-key)