zuplo 6.70.69 → 6.70.71

package/docs/articles/ci-cd-github/local-testing.mdx

@@ -64,7 +64,9 @@ jobs:
         run: npm install
 
       - name: Deploy to Zuplo
-        run: npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+        run:
+          npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "${{
+          github.ref_name }}"
 ```
 
 This workflow:

package/docs/articles/ci-cd-github/pr-preview-environments.mdx

@@ -6,6 +6,19 @@ sidebar_label: PR Preview Environments
 Give every pull request its own Zuplo environment. Reviewers can test changes
 against a live API, and environments clean up automatically when PRs close.
 
+:::caution{title="Pass --environment on pull_request events"}
+
+Workflows triggered by `pull_request` check out the pull request **merge ref**
+(`refs/pull/<number>/merge`), not your branch. Without `--environment`, the
+Zuplo CLI derives the environment name from that ref and creates an environment
+named `pull/<number>/merge` instead of one named after your branch. If anything
+else deploys the same branch — a `push`-triggered workflow, the GitHub
+integration, or a local `zuplo deploy` — you end up with two environments and
+two different URLs for the same branch. Always pass `--environment` with the
+source branch name (`github.head_ref`).
+
+:::
+
 ```yaml title=".github/workflows/pr-workflow.yaml"
 name: PR Workflow
 
@@ -13,6 +26,12 @@ on:
   pull_request:
     types: [opened, synchronize, reopened, closed]
 
+# Runs for the same branch share one queue, so rapid pushes don't race
+# concurrent deploys into the same environment
+concurrency:
+  group: zuplo-preview-${{ github.head_ref }}
+  cancel-in-progress: true
+
 jobs:
   deploy-and-test:
     # Run on PR open/update, not on close
@@ -34,8 +53,12 @@ jobs:
       - name: Deploy to Zuplo
         id: deploy
         shell: bash
+        env:
+          # The PR's source branch — not the pull/<number>/merge ref that
+          # pull_request events check out
+          ENVIRONMENT: ${{ github.head_ref }}
         run: |
-          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" 2>&1)
+          OUTPUT=$(npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "$ENVIRONMENT" 2>&1)
           echo "$OUTPUT"
           DEPLOYMENT_URL=$(echo "$OUTPUT" | grep -oP 'Deployed to \K(https://[^ ]+)')
           echo "url=$DEPLOYMENT_URL" >> $GITHUB_OUTPUT
@@ -71,15 +94,26 @@ jobs:
       - name: Install dependencies
         run: npm install
 
+      - name: Get deployment URL
+        id: get-url
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const comments = await github.rest.issues.listComments({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+            });
+            const match = comments.data
+              .map((c) => c.body.match(/Deployed to: (https:\/\/\S+)/))
+              .find(Boolean);
+            core.setOutput("url", match ? match[1] : "");
+
       - name: Delete environment
+        if: steps.get-url.outputs.url != ''
         run: |
-          # Environment name is based on branch name
-          BRANCH_NAME="${{ github.head_ref }}"
-          # Convert slashes to hyphens (Zuplo convention)
-          ENV_NAME="${BRANCH_NAME//\//-}"
-
           npx zuplo delete \
-            --environment "$ENV_NAME" \
+            --url "${{ steps.get-url.outputs.url }}" \
             --api-key "$ZUPLO_API_KEY" \
             --wait
 ```
@@ -92,12 +126,21 @@ This workflow:
 
 ## How It Works
 
-- The environment name comes from the branch name (`feature/auth` becomes
-  `feature-auth`)
-- Each push to the PR updates the same environment
+- The deploy step passes `--environment` with the PR's source branch name
+  (`github.head_ref`), so the environment is named after the branch — the same
+  name the [GitHub integration](../source-control-setup-github.mdx) would use
+- Each push to the PR updates the same environment, so the environment URL stays
+  stable for the life of the branch
 - Closing the PR (merge or abandon) triggers cleanup
 - The PR comment lets reviewers quickly access the preview
 
+A stable environment URL matters whenever an external system references it
+exactly — an OIDC token audience, a webhook registration, or an IP/URL
+allowlist. Capture the URL from the deploy output rather than constructing it
+from the branch name: the URL hostname uses a normalized, truncated form of the
+environment name plus a unique identifier (see
+[Branch-Based Deployments](../branch-based-deployments.mdx)).
+
 ## Next Steps
 
 - Add [automatic cleanup on branch delete](./cleanup-on-branch-delete.mdx) as a

package/docs/articles/custom-ci-cd-azure.mdx

@@ -38,7 +38,7 @@ npx zuplo deploy --api-key "$ZUPLO_API_KEY"
 npx zuplo test --endpoint https://your-env.zuplo.dev
 
 # Clean up environments you no longer need
-npx zuplo delete --environment pr-123 --api-key "$ZUPLO_API_KEY"
+npx zuplo delete --url "https://my-api-pr-123-d3vp01.zuplo.app" --api-key "$ZUPLO_API_KEY"
 
 # Test locally before deploying
 npx zuplo dev  # starts local server on port 9000

package/docs/articles/custom-ci-cd-bitbucket.mdx

@@ -37,7 +37,7 @@ npx zuplo deploy --api-key "$ZUPLO_API_KEY"
 npx zuplo test --endpoint https://your-env.zuplo.dev
 
 # Clean up environments you no longer need
-npx zuplo delete --environment pr-123 --api-key "$ZUPLO_API_KEY"
+npx zuplo delete --url "https://my-api-pr-123-d3vp01.zuplo.app" --api-key "$ZUPLO_API_KEY"
 
 # Test locally before deploying
 npx zuplo dev  # starts local server on port 9000

package/docs/articles/custom-ci-cd-circleci.mdx

@@ -36,7 +36,7 @@ npx zuplo deploy --api-key "$ZUPLO_API_KEY"
 npx zuplo test --endpoint https://your-env.zuplo.dev
 
 # Clean up environments you no longer need
-npx zuplo delete --environment pr-123 --api-key "$ZUPLO_API_KEY"
+npx zuplo delete --url "https://my-api-pr-123-d3vp01.zuplo.app" --api-key "$ZUPLO_API_KEY"
 
 # Test locally before deploying
 npx zuplo dev  # starts local server on port 9000

package/docs/articles/custom-ci-cd-github.mdx

@@ -47,14 +47,14 @@ The Zuplo CLI handles deployment, testing, and environment management. Your
 GitHub Actions workflow orchestrates when these happen:
 
 ```bash
-# Deploy to Zuplo (environment name from branch or --environment flag)
-npx zuplo deploy --api-key "$ZUPLO_API_KEY"
+# Deploy to Zuplo (pass --environment with the branch name — see below)
+npx zuplo deploy --api-key "$ZUPLO_API_KEY" --environment "$BRANCH_NAME"
 
 # Run tests against any Zuplo environment
 npx zuplo test --endpoint https://your-env.zuplo.dev
 
 # Clean up environments you no longer need
-npx zuplo delete --environment pr-123 --api-key "$ZUPLO_API_KEY"
+npx zuplo delete --url "https://my-api-pr-123-d3vp01.zuplo.app" --api-key "$ZUPLO_API_KEY"
 
 # Test locally before deploying
 npx zuplo dev  # starts local server on port 9000
@@ -64,6 +64,15 @@ Capture the deployment URL from the deploy command output to pass to subsequent
 test steps. The CLI outputs `Deployed to https://...` which you can parse and
 use throughout your workflow.
 
+Always pass `--environment` with the branch name when deploying from GitHub
+Actions, so that every workflow run for a branch updates the same environment.
+Without it, the CLI infers the environment name from the checked-out git ref —
+and on `pull_request` events that's the PR merge ref
+(`refs/pull/<number>/merge`), not your branch, which silently creates a second
+environment with a different URL. The expression
+`${{ github.head_ref || github.ref_name }}` resolves to the branch name on both
+`pull_request` and `push` events.
+
 ## Prerequisites
 
 1. **Disconnect the GitHub integration** — Custom CI/CD replaces automatic

package/docs/articles/custom-ci-cd-gitlab.mdx

@@ -36,7 +36,7 @@ npx zuplo deploy --api-key "$ZUPLO_API_KEY"
 npx zuplo test --endpoint https://your-env.zuplo.dev
 
 # Clean up environments you no longer need
-npx zuplo delete --environment pr-123 --api-key "$ZUPLO_API_KEY"
+npx zuplo delete --url "https://my-api-pr-123-d3vp01.zuplo.app" --api-key "$ZUPLO_API_KEY"
 
 # Test locally before deploying
 npx zuplo dev  # starts local server on port 9000

package/docs/articles/graphql.mdx

@@ -0,0 +1,276 @@
+---
+title: GraphQL on Zuplo
+sidebar_label: GraphQL
+description:
+  Proxy a GraphQL API through your Zuplo gateway and publish a browsable schema
+  reference with a playground in your Dev Portal.
+tags:
+  - backends
+---
+
+Zuplo fronts GraphQL APIs the same way it fronts REST: requests pass through a
+gateway route — with whatever authentication, rate limiting, and
+GraphQL-specific policies you attach — and your Dev Portal documents the schema.
+This guide covers both halves: adding a GraphQL endpoint to your gateway routes,
+then rendering a schema reference and playground in the Dev Portal with
+`@zudoku/plugin-graphql`.
+
+## Prerequisites
+
+- A Zuplo project
+- An upstream GraphQL API to proxy
+- For the Dev Portal section: your project's
+  [Dev Portal](../dev-portal/introduction.mdx) lives in its `docs/` folder. The
+  plugin requires the `zudoku` package version `0.80.1` or newer — check the
+  version in `docs/package.json` and
+  [update the Dev Portal](../dev-portal/updating.mdx) if yours is older.
+
+## Add a GraphQL endpoint to your gateway
+
+A GraphQL API serves every query and mutation from a single endpoint, so the
+gateway route uses the [URL Rewrite handler](../handlers/url-rewrite.mdx) —
+every request goes to exactly the upstream URL — rather than URL Forward, which
+appends the incoming path.
+
+### Add a new GraphQL route
+
+<Stepper>
+
+1. **Open the Route Designer**
+
+   In the Zuplo Portal, open the **Code** tab and click **routes.oas.json**.
+   This opens the Route Designer, which lists your project's existing routes and
+   an **Add** menu.
+
+2. **Add the endpoint**
+
+   Click **Add** and select **GraphQL Endpoint**. This creates a `POST /graphql`
+   route preconfigured with the URL Rewrite handler and a demo upstream. If
+   `/graphql` is already taken, the Portal appends a short suffix (for example
+   `/graphql-b891`) — edit the path to whatever you prefer. GraphQL routes show
+   a **GraphQL** badge in the route list instead of an HTTP method.
+
+3. **Point it at your upstream**
+
+   Expand the new route. Its handler is preset to **URL Rewrite** in the
+   **Request Handler** drop-down; in the URL text box below it, replace the demo
+   URL with your GraphQL API's endpoint, for example
+   `https://api.example.com/graphql`. To use a different backend per
+   environment, reference an [environment variable](./environment-variables.mdx)
+   such as `${env.GRAPHQL_API_URL}`.
+
+4. **Save**
+
+   Save your changes. Your gateway now proxies GraphQL requests at `/graphql`.
+
+</Stepper>
+
+### Mark an existing route as GraphQL
+
+Already proxying a GraphQL API through a regular route? Open the route in the
+Route Designer, click the **⋯** menu at the end of the route's options row (next
+to the CORS and docs toggles), and check **Mark as GraphQL**. This tags the
+route as a GraphQL endpoint without changing its handler or policies.
+
+### The resulting route configuration
+
+Both paths produce a route in `routes.oas.json` with the `x-graphql` extension
+set:
+
+```json title="config/routes.oas.json"
+{
+  "paths": {
+    "/graphql": {
+      "post": {
+        "summary": "GraphQL Endpoint",
+        "x-graphql": true,
+        "x-zuplo-route": {
+          "corsPolicy": "none",
+          "handler": {
+            "export": "urlRewriteHandler",
+            "module": "$import(@zuplo/runtime)",
+            "options": {
+              "rewritePattern": "https://api.example.com/graphql"
+            }
+          },
+          "policies": {
+            "inbound": []
+          }
+        },
+        "operationId": "graphql-1a2bc3d4"
+      }
+    }
+  }
+}
+```
+
+:::tip{title="Secure the endpoint"}
+
+GraphQL has its own attack surface — deeply nested queries, expensive
+operations, and schema introspection. Zuplo ships policies for all three. See
+[Secure your GraphQL API](./graphql-security.mdx) to add complexity limits and
+disable introspection in production.
+
+:::
+
+## Document the API in your Dev Portal
+
+The `@zudoku/plugin-graphql` package renders GraphQL APIs in your Dev Portal
+from a schema. Each plugin instance produces a browsable type reference
+(queries, mutations, objects, enums, and so on) plus a playground, generated
+straight from your schema.
+
+:::caution{title="Beta"}
+
+The GraphQL plugin is in beta. During the beta it isn't available in your
+project's working copy — it only works in projects
+[connected to source control](./source-control.mdx).
+
+:::
+
+<Stepper>
+
+1. **Install the plugin**
+
+   In your project's `docs/` folder (where `zudoku.config.tsx` lives), install
+   the plugin:
+
+   ```bash
+   npm install @zudoku/plugin-graphql
+   ```
+
+   The plugin requires `zudoku` `0.80.1` or newer.
+
+2. **Add a schema**
+
+   Drop a GraphQL schema definition language (SDL) file next to your config:
+
+   ```graphql title="schema.graphql"
+   type Query {
+     product(id: ID!): Product
+   }
+
+   type Product {
+     id: ID!
+     name: String!
+     price: Float!
+   }
+   ```
+
+   Don't have an SDL file handy? Skip this step and introspect a live endpoint
+   at build time with `type: "url"` in the next step — the schema is fetched for
+   you when the portal builds.
+
+3. **Register the plugin**
+
+   Import `graphqlPlugin` and add an instance per API. The `path` is where the
+   docs mount, and `input` points at your schema:
+
+   ```tsx title="zudoku.config.tsx"
+   import { graphqlPlugin } from "@zudoku/plugin-graphql";
+
+   const config = {
+     plugins: [
+       graphqlPlugin({
+         type: "file",
+         input: "./schema.graphql",
+         path: "/graphql/ecommerce",
+         options: {
+           title: "E-Commerce GraphQL API",
+           description: "Products, orders, and customers.",
+           playground: {
+             endpoint: "https://my-gateway.example.com/graphql",
+           },
+         },
+       }),
+     ],
+   };
+
+   export default config;
+   ```
+
+   Set `playground.endpoint` to the gateway route from the first half of this
+   guide so readers run real queries through your gateway. With a file-based
+   schema the plugin doesn't know where your API lives — leave the endpoint
+   unset and the reference pages still render, but the playground asks you to
+   configure `options.playground.endpoint` before it can run operations.
+
+   With `type: "url"`, set `input` to your GraphQL endpoint's URL instead: the
+   schema is fetched via introspection when the portal builds, and the
+   playground defaults to that same URL. You can register the plugin more than
+   once to document several schemas, each with its own `path`.
+
+4. **Link it in the navigation**
+
+   Point a navigation link at the instance's `path`. Set `stack: true` so the
+   API's own pages render as a stacked sub-navigation instead of expanding
+   inline:
+
+   ```tsx title="zudoku.config.tsx"
+   navigation: [
+     {
+       type: "category",
+       label: "Documentation",
+       items: [
+         {
+           type: "link",
+           label: "E-Commerce API",
+           to: "/graphql/ecommerce",
+           stack: true,
+         },
+       ],
+     },
+   ];
+   ```
+
+   Prefer the API as its own top-level section instead? Drop the link at the top
+   level of `navigation` and leave off `stack`. See the
+   [navigation reference](../dev-portal/zudoku/configuration/navigation.mdx) for
+   all link, category, and stacking options.
+
+</Stepper>
+
+### Plugin options
+
+All options live under the instance's `options` key:
+
+| Option                | Type      | Description                                                                                                                                            |
+| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `title`               | `string`  | Display title for the API's overview page.                                                                                                             |
+| `description`         | `string`  | Short description shown on the overview page.                                                                                                          |
+| `showDeprecated`      | `boolean` | Include deprecated fields and operations in the reference.                                                                                             |
+| `playground.enabled`  | `boolean` | Show the playground. Defaults to `true`.                                                                                                               |
+| `playground.endpoint` | `string`  | URL the playground sends operations to. Defaults to `input` for `type: "url"`. File schemas have no default; the playground prompts for one until set. |
+| `playground.headers`  | `object`  | Default headers the playground sends with each operation.                                                                                              |
+
+## Verify it worked
+
+Open the
+[**Environments**](https://portal.zuplo.com/+/account/project/environments) tab
+in the Zuplo Portal — your build is listed there along with the URLs for both
+your gateway and your Dev Portal. Send a query through the gateway URL:
+
+```bash
+curl https://my-gateway.example.com/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query":"{ __typename }"}'
+```
+
+A working route returns a response from your upstream, such as
+`{"data":{"__typename":"Query"}}`.
+
+For the Dev Portal, open its URL from the **Environments** tab (or run
+`npm run dev` in your `docs/` folder) and go to the plugin's `path` (for example
+`/graphql/ecommerce`). The overview page lists the schema's types, and the
+playground runs operations against your configured endpoint.
+
+## Next steps
+
+- [Secure your GraphQL API](./graphql-security.mdx) — complexity limits and
+  introspection policies
+- [Testing GraphQL queries](./testing-graphql.mdx) — test the endpoint from the
+  Zuplo Portal or external tools
+- [URL Rewrite handler](../handlers/url-rewrite.mdx) — full reference for the
+  handler GraphQL routes use
+- [MCP Server GraphQL endpoints](../mcp-server/graphql.mdx) — expose GraphQL
+  queries as MCP tools for AI agents

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

@@ -52,6 +52,190 @@ curl \
   --header "Authorization: Bearer $ZAPI_KEY"
 ```
 
+## Bucket monetization configuration
+
+Each bucket has an optional `MonetizationConfiguration` that holds bucket-wide
+behavior — multi-subscription support, plan display order, plan-level overrides,
+and the default payment grace period. The configuration is read by the runtime
+and the Developer Portal; it is not stored in OpenMeter.
+
+### Read
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/monetization-configuration \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+When no configuration row exists for the bucket, the endpoint returns a default
+body with `multipleSubscriptionsEnabled: false`, an empty `planOrder`, empty
+`planSettings`, and `maxPaymentOverdueDays: 3`.
+
+### Upsert
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/monetization-configuration \
+  --request PUT \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "multipleSubscriptionsEnabled": false,
+  "planOrder": ["free", "starter", "pro", "enterprise"],
+  "planSettings": {
+    "pro": { "visiblePhases": ["default"] }
+  },
+  "maxPaymentOverdueDays": 7
+}
+EOF
+```
+
+| Field                          | Type       | Description                                                                                                                                                                                         |
+| ------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `multipleSubscriptionsEnabled` | `boolean`  | Stored on the bucket. Reserved for future multi-subscription rules; today the Developer Portal create-subscription path enforces a single active subscription per customer regardless of this flag. |
+| `planOrder`                    | `string[]` | Ordered list of plan keys; drives pricing-page sort and upgrade/downgrade direction during plan changes                                                                                             |
+| `planSettings`                 | `object`   | Per-plan overrides keyed by plan key. The supported sub-key today is `visiblePhases` — an array of phase keys that should appear on the pricing page                                                |
+| `maxPaymentOverdueDays`        | `integer`  | Bucket-default payment grace period. Must be ≥ 0. Defaults to `3` when not set                                                                                                                      |
+
+The request body must include at least one of these fields. All four fields are
+optional in the request — the upsert preserves any field you don't send.
+
+`planOrder` is consumed when a customer changes plans through the Developer
+Portal: a target plan whose index is greater than or equal to the current plan's
+index is treated as an upgrade (immediate timing); a lower index is treated as a
+downgrade (next-billing-cycle timing). Plans not listed in `planOrder` default
+to upgrade timing.
+
+`maxPaymentOverdueDays` is the lowest-precedence default for the payment grace
+period. See
+[Subscription and payment validation](./monetization-policy.md#subscription-and-payment-validation)
+for the full precedence chain (customer metadata → plan metadata → bucket
+configuration → built-in default).
+
+### Delete
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/monetization-configuration \
+  --request DELETE \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+After deletion, GET returns the default body again.
+
+## Stripe setup and billing readiness
+
+Most users connect Stripe through the
+[Zuplo Portal](./stripe-integration.md#connecting-your-stripe-account). For
+automated provisioning — CI scripts, infrastructure-as-code, or self-hosted
+control planes — the same flow is available via these API endpoints.
+
+### Install the Stripe app
+
+Connect a Stripe account to a bucket and create the default billing profile in
+one call:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/setup/stripe \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "apiKey": "rk_test_...",
+  "name": "Stripe Billing Profile",
+  "taxEnabled": false,
+  "taxEnforced": false,
+  "country": "US"
+}
+EOF
+```
+
+The endpoint validates the Stripe key prefix against the bucket's environment:
+
+- Working-copy and preview buckets accept `sk_test_*` or `rk_test_*`
+- Production buckets accept `sk_live_*` or `rk_live_*`
+
+The response returns the installed `appId`. The endpoint fails with a
+`409 Conflict` if a Stripe app is already installed for the bucket.
+
+### Read the current Stripe setup
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/setup/stripe \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+Returns the connected Stripe app summary and the billing profiles linked to it.
+
+### Create an additional billing profile
+
+To attach more billing profiles to the same Stripe app:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/setup/stripe/$STRIPE_APP_ID/billing-profile \
+  --request POST \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "name": "EU Billing Profile",
+  "taxEnabled": true,
+  "taxEnforced": false,
+  "country": "DE"
+}
+EOF
+```
+
+### Check billing readiness
+
+A lightweight check for tooling that gates deploys on Stripe being connected:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/billing-readiness \
+  --header "Authorization: Bearer $ZAPI_KEY"
+```
+
+Response:
+
+```json
+{
+  "hasStripeApp": true,
+  "stripeAppId": "app_01H...",
+  "hasDefaultBillingProfile": true,
+  "defaultBillingProfileId": "bp_01H..."
+}
+```
+
+Use this in setup wizards to gate the UI on whether Stripe is connected.
+
+### Update a connected app
+
+Rotate the Stripe key on an existing app, or update its name and metadata:
+
+```shell
+curl \
+  https://dev.zuplo.com/v3/metering/$BUCKET_ID/apps/$APP_ID \
+  --request PUT \
+  --header "Authorization: Bearer $ZAPI_KEY" \
+  --header "Content-Type: application/json" \
+  --data @- << EOF
+{
+  "type": "stripe",
+  "name": "Stripe Billing Profile",
+  "secretAPIKey": "rk_test_..."
+}
+EOF
+```
+
+The same key-prefix validation applies — a live key is rejected on a
+non-production bucket and vice versa.
+
 ## API Reference
 
 For complete API operations, see the API Reference documentation:

package/docs/articles/monetization/meters.mdx

@@ -58,10 +58,10 @@ carries the quantity:
 `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
+`subscription` field for that) and does not 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.
 
 :::

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

@@ -145,7 +145,10 @@ below it:
 
 1. **Customer metadata** — `zuplo_max_payment_overdue_days` on the customer
 2. **Plan metadata** — `zuplo_max_payment_overdue_days` on the plan
-3. **Default** — `3` days
+3. **Bucket configuration** —
+   [`maxPaymentOverdueDays`](./api-access.mdx#bucket-monetization-configuration)
+   on the bucket's monetization configuration
+4. **Default** — `3` days
 
 Set the value to `0` to block requests immediately when payment is overdue.