Guides

Monetization Policy Reference

Copy page

The MonetizationInboundPolicy is the gateway enforcement mechanism. It runs on every request to a protected route, authenticates the API key, checks the customer's subscription and payment status, enforces quota, meters the request, and allows or blocks access.

Basic configuration

Add the policy to your policies.json:

Code
{
  "name": "monetization-inbound",
  "policyType": "monetization-inbound",
  "handler": {
    "export": "MonetizationInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "meters": {
        "api_requests": 1
      }
    }
  }
}

Then reference it in your route's inbound policy pipeline:

Code
{
  "x-zuplo-route": {
    "policies": {
      "inbound": ["monetization-inbound"]
    }
  }
}

Configuration options

Option	Type	Default	Description
meters	object	(required)	Map of meter keys to increment values
meterOnStatusCodes	string or number[]	"200-299"	Status code range to meter
authHeader	string	"authorization"	Header to read the API key from
authScheme	string	"Bearer"	Expected auth scheme prefix
cacheTtlSeconds	number	60	How long to cache subscription data (minimum 60s)

meters

The meters option defines which meters to increment and by how much when a request is processed. Values must be positive numbers.

Code
// Increment the api_requests meter by 1 per request
{ "meters": { "api_requests": 1 } }

// Increment multiple meters simultaneously
{ "meters": { "api_requests": 1, "api_credits": 5 } }

// Increment by a fixed amount per request (expensive endpoint)
{ "meters": { "api_credits": 10 } }

meterOnStatusCodes

Controls which responses count toward metering. By default, only successful responses (2xx) are metered.

Code
// Only meter successful responses (default)
{ "meterOnStatusCodes": "200-299" }

// Only meter 200 OK
{ "meterOnStatusCodes": "200" }

// Meter success and redirects
{ "meterOnStatusCodes": "200-399" }

// Comma-separated ranges
{ "meterOnStatusCodes": "200, 201, 300-304" }

// Array of specific status codes
{ "meterOnStatusCodes": [200, 201, 202] }

This is important for fairness: if your backend returns a 500 error, you probably don't want to charge the customer for that request.

authHeader

The header to read the API key from. Defaults to "authorization".

authScheme

The expected auth scheme prefix. Defaults to "Bearer". The policy expects the header value in the format {authScheme} {apiKey}.

cacheTtlSeconds

How long to cache subscription and entitlement data, in seconds. Defaults to 60 with a minimum of 60. Increasing this value reduces calls to the gateway service but means entitlement changes take longer to propagate.

Subscription and payment validation

The policy checks payment status on every request. Access is granted when:

• The subscription is active and not expired
• Payment status is paid or not_required (free plans)

When payment fails, a configurable grace period (default 3 days) allows continued access while retries are attempted. After the grace period, access is blocked until payment succeeds.

The grace period is configurable via metadata on the plan or customer:

• Plan metadata key: zuplo_max_payment_overdue_days
• Customer metadata key: zuplo_max_payment_overdue_days
• Default: 3 (days)

Multiple policies for different routes

Different routes can have different metering configurations. Define multiple policy instances:

Code
[
  {
    "name": "monetization-standard",
    "policyType": "monetization-inbound",
    "handler": {
      "export": "MonetizationInboundPolicy",
      "module": "$import(@zuplo/runtime)",
      "options": {
        "meters": { "api_requests": 1 }
      }
    }
  },
  {
    "name": "monetization-ai",
    "policyType": "monetization-inbound",
    "handler": {
      "export": "MonetizationInboundPolicy",
      "module": "$import(@zuplo/runtime)",
      "options": {
        "meters": { "api_requests": 1, "tokens": 1 }
      }
    }
  },
  {
    "name": "monetization-premium",
    "policyType": "monetization-inbound",
    "handler": {
      "export": "MonetizationInboundPolicy",
      "module": "$import(@zuplo/runtime)",
      "options": {
        "meters": { "api_credits": 10 }
      }
    }
  }
]

Apply each to the appropriate routes:

Code
// Simple lookup -> 1 request meter
"/api/v1/search": { "inbound": ["monetization-standard"] }

// AI endpoint -> 1 request + token metering
"/api/v1/analyze": { "inbound": ["monetization-ai"] }

// Premium endpoint -> 10 credits
"/api/v1/bulk-export": { "inbound": ["monetization-premium"] }

Dynamic metering

For AI APIs and other variable-cost endpoints, you may need to meter based on the response — for example, counting the number of tokens returned by an LLM.

Use the setMeters and addMeters static methods to set meter values programmatically at runtime from a custom policy or handler:

Code
import { MonetizationInboundPolicy } from "@zuplo/runtime";

// In a custom outbound policy, set meters based on the response
export default async function meterTokens(response, request, context) {
  if (response.ok) {
    const body = await response.json();
    const tokens = body.usage?.total_tokens ?? 0;

    MonetizationInboundPolicy.setMeters(context, {
      tokens_used: tokens,
    });
  }
  return response;
}

You can also use addMeters to add to existing meter values rather than replacing them:

Code
MonetizationInboundPolicy.addMeters(context, {
  api_credits: creditsConsumed,
});

When using dynamic metering, configure the policy with the meter key but omit it from the static meters option (or set it to 0), and set the value dynamically in your handler.

Error responses

The policy returns 403 Forbidden for all error conditions. Responses follow the RFC 7807 Problem Details format:

Code
{
  "type": "https://httpproblems.com/http-status/403",
  "title": "Forbidden",
  "status": 403,
  "detail": "API Key has exceeded the allowed limit for \"api_requests\" meter.",
  "instance": "/api/v1/resource",
  "trace": {
    "timestamp": "2026-01-15T10:00:00Z",
    "requestId": "req_abc123",
    "buildId": "build_xyz"
  }
}

Common error details:

Condition	detail message
No auth header	"No Authorization Header"
Wrong auth scheme	"Invalid Authorization Scheme"
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."
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."

Pipeline ordering

The monetization policy should be the first policy in the inbound pipeline since it handles authentication:

Code
1. monetization-inbound  → Authenticates, checks subscription, enforces quota, meters usage
2. rate-limiting         → (Optional) Per-second/per-minute spike protection
3. caching               → (Optional) Response caching
4. → Route handler       → Your API logic

If you still want per-second or per-minute rate limiting on top of monthly quotas, add a standalone rate-limiting policy after the monetization policy. These serve different purposes: monetization enforces billing quotas, while rate limiting protects against traffic spikes.