zuplo 6.67.32 → 6.68.0

package/docs/articles/monetization/troubleshooting.md

@@ -0,0 +1,272 @@
+---
+title: Troubleshooting & FAQ
+sidebar_label: Troubleshooting
+---
+
+:::note{title="Beta"}
+
+API Monetization is in beta and free to try. The APIs are stable but should be
+evaluated in non-production environments first. To go to production, contact
+[sales@zuplo.com](mailto:sales@zuplo.com). Production pricing has not yet been
+announced.
+
+:::
+
+## Common issues
+
+### Customer gets 403 Forbidden instead of expected access
+
+**Symptom:** Authenticated customer with an active subscription receives
+`403 Forbidden` instead of a successful response.
+
+**Causes and fixes:**
+
+1. **Payment is overdue.** Check the subscription's payment status via the API.
+   If payment has failed and the grace period (default 3 days) has passed,
+   access is blocked.
+
+   ```bash
+   curl https://dev.zuplo.com/v3/metering/{bucketId}/customers/{CUSTOMER_ID}/subscriptions \
+     -H "Authorization: Bearer {API_KEY}"
+   ```
+
+   Fix: Either resolve the payment issue in Stripe, or adjust the grace period
+   via `zuplo_max_payment_overdue_days` metadata on the plan or customer.
+
+2. **Customer is using the wrong API key.** Each subscription generates its own
+   key. If the customer has multiple subscriptions or regenerated their key,
+   they may be using an old or unrelated key.
+
+   Fix: Have the customer check their active key in the Developer Portal →
+   Subscriptions page.
+
+3. **Customer has no subscription.** If the customer authenticated but never
+   subscribed to a plan, they get 403 on monetized routes.
+
+   Fix: Direct the customer to subscribe to a plan (even a free tier).
+
+### Customer gets 403 Forbidden for quota exceeded
+
+**Symptom:** Customer's requests are being blocked and the error detail mentions
+exceeding a meter limit.
+
+**Causes and fixes:**
+
+1. **Separate rate-limiting policy is blocking them.** If you have both a
+   `MonetizationInboundPolicy` (monthly quota) and a standalone rate-limiting
+   policy (per-second/per-minute), the rate limiter may be triggering before the
+   monetization quota is reached.
+
+   Fix: Check if a per-second/per-minute rate limit is configured. The response
+   body detail message will indicate which limit was hit.
+
+2. **Meter counting both successes and failures.** The default
+   `meterOnStatusCodes` is `"200-299"`, so only successful responses are
+   metered. If you changed this to a broader range, failed requests (4xx, 5xx
+   from your backend) count against the quota.
+
+   Fix: Set `meterOnStatusCodes` to `"200-299"` to only count successful
+   responses.
+
+3. **Multiple meters consuming the same quota.** If a single request increments
+   a meter by more than 1 (e.g., `"api_credits": 10`), the quota depletes faster
+   than the customer expects.
+
+   Fix: Verify the meter increment values in your policy configuration match
+   what your pricing page communicates.
+
+### Stripe Checkout redirects but subscription isn't created in Zuplo
+
+**Symptom:** Customer completes Stripe Checkout successfully, but the Developer
+Portal shows no active subscription.
+
+**Causes and fixes:**
+
+1. **Preview environment mismatch.** If you tested in a preview deployment but
+   the checkout was configured for a different environment, the subscription may
+   have been created in the wrong bucket.
+
+   Fix: Ensure you are testing against the correct environment (working copy,
+   preview, or production).
+
+2. **Stripe test mode / live mode mismatch.** Products and subscriptions in
+   Stripe test mode are invisible to live mode and vice versa.
+
+   Fix: Verify you're looking at the correct mode in both Stripe and Zuplo.
+
+### Usage dashboard shows zero despite active API traffic
+
+**Symptom:** Customer is making successful API requests, but the usage dashboard
+in the Developer Portal shows 0 usage.
+
+**Causes and fixes:**
+
+1. **Monetization policy is not applied to the route.** The
+   `MonetizationInboundPolicy` must be in the inbound policy pipeline for
+   metering to occur. If the route only has a different authentication policy
+   (no monetization policy), requests go through but aren't metered.
+
+   Fix: Verify the `monetization-inbound` policy is listed in the route's
+   inbound policies.
+
+2. **`meterOnStatusCodes` excludes the response status.** If set to `"200"` but
+   your API returns `201 Created`, those requests won't be metered.
+
+   Fix: Widen the status code range (e.g., `"200-299"`).
+
+### Plan changes don't take effect
+
+**Symptom:** Customer upgrades their plan in the Developer Portal, but their
+entitlements don't change.
+
+**Causes and fixes:**
+
+1. **Plan was updated but not published.** Plans in `draft` status aren't
+   visible to customers, and updates to active plans need to be re-published.
+
+   Fix: Check the plan status. Publish if it's still in draft.
+
+2. **Caching lag.** Entitlement changes propagate in near-real-time, but there
+   can be a brief propagation window (typically under 60 seconds based on
+   `cacheTtlSeconds`).
+
+   Fix: Wait a minute and retry. If the issue persists, check the subscription
+   via the API to verify the plan change was recorded.
+
+## Debugging tools
+
+### Check subscription state via the API
+
+```bash
+# List subscriptions for a customer
+curl https://dev.zuplo.com/v3/metering/{bucketId}/customers/{CUSTOMER_ID}/subscriptions \
+  -H "Authorization: Bearer {API_KEY}"
+
+# Check subscription access and entitlements
+curl https://dev.zuplo.com/v3/metering/{bucketId}/subscriptions/{subscriptionId}/access \
+  -H "Authorization: Bearer {API_KEY}"
+```
+
+### Check meter usage
+
+```bash
+# Query meter usage for the current month
+curl -X POST https://dev.zuplo.com/v3/metering/{bucketId}/meters/{meterIdOrSlug}/query \
+  -H "Authorization: Bearer {API_KEY}" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "subject": "{SUBSCRIPTION_ID}",
+    "from": "2026-03-01T00:00:00Z",
+    "to": "2026-03-31T23:59:59Z",
+    "windowSize": "DAY"
+  }'
+```
+
+### Test with cURL
+
+Verify the full flow manually:
+
+```bash
+# Make a request to a monetized endpoint
+curl -v -H "Authorization: Bearer {CUSTOMER_API_KEY}" \
+  https://your-api.zuplo.dev/api/v1/resource
+
+# Check the response status and body for error details
+# 403 with detail message indicates auth, payment, or quota issues
+```
+
+## FAQ
+
+### Can I have both free and paid plans?
+
+Yes. Create a free plan with `price: null` and `isSoftLimit: false` on the
+entitlement. Free plans that don't require a credit card skip Stripe Checkout
+entirely — the customer gets access immediately after clicking "Start Free."
+
+### Can a customer have multiple subscriptions?
+
+Yes. Each subscription generates its own API key. The customer uses the
+appropriate key for each subscription. This supports scenarios like a primary
+subscription plus a credit pack, or separate subscriptions for different API
+products.
+
+### What happens if Stripe is down?
+
+Zuplo caches subscription and quota state locally. If Stripe is temporarily
+unavailable, existing customers continue to have access based on their cached
+subscription state. New subscriptions and plan changes require Stripe to be
+available.
+
+### Can I use currencies other than USD?
+
+Yes. Plans support any ISO 4217 currency code. Set the `currency` field when
+creating a plan. You can offer the same plan in multiple currencies by creating
+separate plan objects (e.g., `pro-usd` and `pro-eur`).
+
+### How are overages calculated?
+
+Overages are modeled using graduated tiered pricing. The first tier covers the
+included allowance at a flat price, and subsequent tiers charge per-unit for
+usage beyond the allowance. See [Pricing Models](./pricing-models.mdx) for
+details.
+
+### Can I set spending limits for pay-as-you-go customers?
+
+You can set a hard entitlement limit that acts as a spending cap (e.g., max
+100,000 requests regardless of willingness to pay). Alternatively, use a custom
+policy to check current usage against a configurable limit, or set up Stripe
+billing alerts to notify customers approaching a threshold.
+
+### Do meters count retried requests?
+
+Yes. Each request that hits the gateway is independently metered. If a client
+retries a failed request, both the original and retry are metered (subject to
+`meterOnStatusCodes` filtering). This is by design — your infrastructure handled
+both requests.
+
+### Can I migrate from Amberflo/Moesif/OpenMeter?
+
+Yes. The third-party metering integrations (Amberflo, Moesif, OpenMeter
+policies) are separate from the native Zuplo Monetization. You can run them in
+parallel during migration:
+
+1. Add the `MonetizationInboundPolicy` alongside your existing third-party
+   policy
+2. Let both meter simultaneously for a comparison period
+3. Once you've verified parity, remove the third-party policy
+4. Decommission the third-party metering service
+
+### Is there an SLA on metering accuracy?
+
+Zuplo meters in the request path — every request that gets a response is metered
+synchronously. There's no batch processing, no eventual consistency window, and
+no sampling. If the customer's API call succeeded (based on
+`meterOnStatusCodes`), it's counted.
+
+### Can I customize the 403 response body?
+
+Yes. Use a custom outbound policy to transform the `403` response when it's a
+quota error:
+
+```typescript
+export default async function customQuotaResponse(response, request, context) {
+  if (response.status === 403) {
+    const body = await response.json();
+    if (body.detail?.includes("exceeded the allowed limit")) {
+      return new Response(
+        JSON.stringify({
+          error: "quota_exceeded",
+          message:
+            "You've exceeded your API quota. Upgrade your plan for more requests.",
+          upgrade_url: "https://developers.your-company.com/pricing",
+        }),
+        {
+          status: 429,
+          headers: response.headers,
+        },
+      );
+    }
+  }
+  return response;
+}
+```

package/docs/articles/monetization-custom.mdx

@@ -0,0 +1,71 @@
+---
+title: Custom API Monetization
+sidebar_label: Custom Monetization
+---
+
+Zuplo's [Monetization](./monetization/index.mdx) supports advanced requirements
+out of the box. For organizations with needs beyond the standard offering, Zuplo
+provides additional capabilities and dedicated support.
+
+## Custom monetization capabilities
+
+### Advanced billing models
+
+Plans can combine multiple billing strategies in a single subscription:
+
+- **Multi-dimensional metering** — Track and bill on several metrics
+  simultaneously (requests, tokens, data volume)
+- **Negotiated contracts** — Create
+  [private plans](./monetization/private-plans.md) with custom pricing for
+  individual customers
+- **Multiple currencies** — Price plans in different currencies for regional
+  markets
+- **Complex phase structures** — Model free trials, commitment terms, and
+  automatic conversions using [plan phases](./monetization/plans.mdx)
+
+### Global quota enforcement
+
+Zuplo's globally distributed infrastructure ensures consistent monetization
+behavior everywhere:
+
+- **Edge-native metering** — Usage is tracked at the edge, close to where
+  requests are served
+- **Low-latency enforcement** — Quota checks add minimal overhead to request
+  processing
+- **Real-time synchronization** — Usage data is synchronized globally in near
+  real-time
+- **Resilient design** — Quota enforcement continues to operate during network
+  partitions
+
+### Custom integrations
+
+For organizations with existing billing infrastructure:
+
+- **Custom billing systems** — Connect Zuplo Monetization to proprietary ERP,
+  CRM, or billing platforms using the
+  [Developer API](./monetization/api-access.mdx)
+- **Revenue sharing** — Implement partner or marketplace billing models with
+  custom policies
+- **Audit trails** — Full visibility into metering and billing events for
+  compliance
+
+### Developer Portal
+
+Customers get the full self-serve experience through the
+[Developer Portal](./monetization/developer-portal.md):
+
+- **White-label portals** — Fully branded experience for your customers
+- **Self-service subscription management** — Customers manage upgrades,
+  downgrades, and cancellations
+- **Usage dashboards** — Real-time visibility into consumption and remaining
+  quota
+- **API key management** — Customers create and manage their own API keys
+
+## Getting started
+
+Zuplo Monetization is available on all plans. Follow the
+[Quickstart](./monetization/quickstart.md) to set up metering, plans, and Stripe
+billing in under 30 minutes.
+
+For enterprise-specific requirements — custom contracts, dedicated support, or
+integration assistance — [contact the Zuplo team](mailto:sales@zuplo.com).

package/docs/articles/monetization-integrations.mdx

@@ -0,0 +1,104 @@
+---
+title: Third-Party Monetization Integrations
+sidebar_label: Third-Party Integrations
+---
+
+Zuplo's [built-in Monetization](./monetization/index.mdx) handles metering,
+billing, and quota enforcement natively at the gateway. For teams with existing
+billing infrastructure or specialized requirements, Zuplo also integrates with
+third-party metering and billing platforms through policies and the programmable
+gateway.
+
+## When to use third-party integrations
+
+Third-party integrations make sense when you:
+
+- Already have an established billing pipeline you want to keep
+- Need a platform-specific feature that Zuplo Monetization does not yet cover
+- Want to combine Zuplo's gateway with a dedicated analytics or metering vendor
+
+For most teams starting fresh, the
+[built-in Monetization](./monetization/index.mdx) is the fastest path — it
+removes the need to synchronize state between separate metering, billing, and
+gateway systems.
+
+## Available integrations
+
+### Amberflo
+
+The [Amberflo Metering Policy](../policies/amberflo-metering-inbound.mdx)
+enables real-time usage metering and billing through
+[Amberflo](https://www.amberflo.io/), a usage-based billing platform:
+
+- **Real-time event ingestion** — Track usage events with sub-second latency
+- **Flexible metering** — Define custom meters for any billable metric
+- **Usage-based pricing** — Support complex pricing models and tiers
+- **Customer dashboards** — Provide usage visibility to your customers
+
+### Moesif
+
+The [Moesif Analytics Policy](../policies/moesif-inbound.mdx) integrates with
+[Moesif](https://www.moesif.com/) for API analytics and monetization:
+
+- **API analytics** — Deep insights into API usage patterns and customer
+  behavior
+- **Usage tracking** — Monitor API calls, latency, and error rates
+- **Customer segmentation** — Analyze usage by customer cohorts
+- **Billing alerts** — Set up notifications for usage thresholds
+
+Learn how Zuplo and Moesif work together:
+[API Observability and Monetization at the Edge](https://www.moesif.com/blog/api-monetization/Moesif-Zuplo-API-Observability-and-Monetization-At-The-Edge/)
+
+### Stripe (direct)
+
+[Stripe](https://stripe.com) can be used directly with Zuplo's programmable
+gateway for custom billing flows:
+
+- **Custom integrations** — Use Stripe's APIs with Zuplo's programmable gateway
+- **Webhooks** — Process subscription events and update access in real-time with
+  the
+  [Stripe Webhook Verification Policy](../policies/stripe-webhook-verification-inbound.mdx)
+- **Tiered access** — Different rate limits and features per subscription level
+
+:::tip
+
+Zuplo's built-in Monetization already includes a
+[native Stripe integration](./monetization/stripe-integration.md) that handles
+subscription management, invoicing, and payment collection automatically. Use
+the direct Stripe integration only if you need full control over the billing
+flow.
+
+:::
+
+## Building custom integrations
+
+Zuplo's programmable gateway lets you integrate with any billing or metering
+provider.
+
+### Custom policies
+
+Create [custom inbound](../policies/custom-code-inbound.mdx) and
+[outbound policies](../policies/custom-code-outbound.mdx) to:
+
+- Send usage events to an external metering service
+- Look up entitlements from an external billing system
+- Calculate dynamic pricing based on request or response characteristics
+
+### Hooks
+
+Use Zuplo's [hooks system](../programmable-api/hooks.mdx) to:
+
+- Forward usage data to your billing pipeline
+- Update customer limits in real-time
+- Stream metrics to external systems using plugins like the
+  [Azure Event Hubs Plugin](./plugin-azure-event-hubs.mdx)
+
+### Developer Portal
+
+The [Zuplo Developer Portal](../dev-portal/introduction.mdx) supports custom
+pages and plugins for billing UI:
+
+- [Custom pages](../dev-portal/zudoku/guides/custom-pages.md) for pricing,
+  billing, and account management
+- [Custom plugins](../dev-portal/zudoku/custom-plugins.md) to embed billing
+  widgets and dashboards

package/docs/articles/monitoring-your-gateway.mdx

@@ -0,0 +1,53 @@
+---
+title: Ensuring the integrity of your gateway with proactive monitoring
+sidebar_label: Proactive monitoring
+---
+
+Reliability and performance of your gateway are paramount. Zuplo's commitment to
+operational excellence aims to provide seamless, uninterrupted service.
+Nevertheless, the complex and customizable nature of gateways necessitates a
+vigilant approach to monitoring by users. Proactive, end-to-end monitoring
+becomes not just a recommendation but a requisite for maintaining the integrity
+of your mission-critical gateway.
+
+Zuplo makes every effort to actively monitor our core services and deliver 100%
+up-time for your gateway. However, there are many ways in which you can cause
+issues with your gateway, for example:
+
+### Common Sources of Disruptions
+
+Several factors can compromise the functionality of your gateway, including but
+not limited to:
+
+- Misconfigured environment variables: Simple errors like a misspelled URL or
+  incorrect shared secret can take your gateway down.
+- Coding Errors: The flexibility of Zuplo allows for extensive customization
+  and, like any software, has the potential to cause disruption if bad code is
+  deployed.
+
+This means we strongly recommend that you have active end-to-end monitoring of
+each network configuration of your gateway. In fact, for some Enterprise
+Agreements we mandate this to offer a higher SLA.
+
+## Pro-active monitoring
+
+We recommend doing this by having a health check endpoint for each network
+configuration. For example, if you have 3 backends and 2 tunnels we would
+recommend having 3 health-check endpoints on Zuplo with each going through the
+same combination of network hops that your gateway routes will need to leverage.
+
+![Health Checks](../../public/media/monitoring-your-gateway/health-checks.png)
+
+Some customers choose to go further, and have their backend health-check only
+return 'OK' if it also verifies other critical dependencies, like a database
+connection or dependent service, are also operational.
+
+Most customers use a monitoring service, here are a few examples:
+
+- [Checkly](https://checklyhq.com)
+- [API Context](https://apicontext.com)
+- [Datadog](https://www.datadoghq.com/dg/apm/synthetics/api-test)
+
+In addition, we recommend using our [Enterprise Log Plugins](./logging.mdx) to
+send log events to partners like Datadog and set up volume based alerts from any
+unusually increased error rates from your custom code or dependent services.