The can() Endpoint

The can() endpoint is the core of Nozle’s entitlement system.

Request

GET /api/v1/can?customer_id=cust_123&feature=api_calls
Authorization: Bearer sk_nozle_...

Call this endpoint from a trusted backend with a restricted secret key. Derive cust_123 from the authenticated application user; publishable keys are rejected.

Query parameter	Required	Description
`customer_id`	yes	External customer ID
`feature`	yes	Feature code
`subscription_id`	no	External ID of one current subscription of the customer. Evaluates that subscription
`entity_id`	no	External ID of an Entity. Evaluates the Entity’s own subscription, else the customer’s own subscription
`metadata`	no	URL-encoded JSON object of event properties for the economics estimate. It does not filter usage: `used`, `limit` and `remaining` cover all of the feature’s usage

See Which subscription is checked.

Response

{
  "allowed": true,
  "used": 1500,
  "limit": 10000,
  "remaining": 8500,
  "economics": {
    "status": "estimated",
    "currency": "USD",
    "estimated_incremental_cost": "0.05",
    "estimated_incremental_revenue": "0.10",
    "estimated_incremental_margin": "0.05",
    "estimated_margin_percent": "50",
    "rule_version_ids": ["4d946b17-aafe-4c6d-9863-4b69049fe6ef"],
    "includes": ["feature_event_cost"],
    "excludes": ["future_detailed_cost_events", "shared_period_costs", "finalized_invoice_adjustments"],
    "calculated_at": "2026-09-02T12:00:00Z"
  },
  "policy": {
    "version_id": "b0251ae2-86cd-48f5-a34a-4c423f6d7821",
    "mode": "warn",
    "on_unavailable": "warn",
    "minimum_margin_percent": "20",
    "maximum_snapshot_age_seconds": 30,
    "decision": "allow",
    "reason": "within_policy"
  }
}

Field reference

Field	Type	Description
`allowed`	`boolean`	Whether the customer can use this feature
`reason`	`string?`	Why access was denied. Omitted when `allowed` is `true`. See Denial reasons
`feature_type`	`string?`	Type of the feature. Not returned when the feature or the subscription is missing
`configuration`	`object?`	Configuration values granted by the plan for a non-metered feature
`used`	`number`	Usage in the current billing period, or the running total for a recurring Feature. Also the real usage of a metered Feature that has no entitlement and is only priced by a charge. `0` when the denial is decided before usage is read
`limit`	`number \| null`	Usage cap for this feature. `null` when there is no cap, and for a Feature priced only by a charge
`remaining`	`number \| null`	`limit - used`, never below `0`. `null` when `limit` is `null`
`overage`	`boolean?`	`true` when usage has reached a soft limit; the request is still allowed. Omitted otherwise
`economics.status`	`string`	`estimated`, `not_configured`, `unavailable`, or `stale`
`economics.currency`	`string?`	The organization’s reporting currency
`economics.estimated_incremental_cost`	`string?`	Exact decimal incremental cost for the proposed Feature Event
`economics.estimated_incremental_revenue`	`string?`	Exact decimal usage revenue of the proposed call: the standard charge’s unit price × the call’s units (1 for a count Feature; the value of the Feature’s `field_name` in `metadata` for a sum Feature)
`economics.estimated_incremental_margin`	`string?`	Estimated revenue minus estimated cost
`economics.estimated_margin_percent`	`string?`	Margin percentage when estimated revenue is greater than zero
`economics.rule_version_ids`	`string[]?`	Immutable Cost Rule versions used by the estimate
`economics.includes`	`string[]?`	Cost categories included in the estimate
`economics.excludes`	`string[]?`	Costs unavailable before execution, such as future Detailed Cost Events
`economics.calculated_at`	`string`	Time at which the estimate was calculated
`policy`	`object?`	Versioned policy, thresholds, fallback behavior, decision, and reason

Runtime behavior

The service may cache entitlement and usage state. Always treat the returned decision as point-in-time and enforce it immediately before protected work. A subscription on an override plan (a plan made from a catalog plan for one customer, for example a negotiated price or a subscription created from a quote) gets the entitlements and usage limits of the catalog plan it was made from. Its usage is still priced with the override plan’s own charges. The optional economics object is also point-in-time, but it is not a financial ledger entry. Calling /can never consumes usage, changes a pricing period, or records cost. If a Feature uses detailed_events_only, the estimate is unavailable because the actual Cost Events do not exist yet. If it uses add_both, the known Feature Event Cost is returned and future_detailed_cost_events appears in excludes. An estimate older than the policy’s maximum_snapshot_age_seconds is returned as stale and follows on_unavailable. Estimated revenue is the standard charge’s unit price × the units of this call. A count Feature adds 1 unit. A sum Feature adds the value of its value property (field_name) in the call’s metadata, for example {"tokens": 500}; without that value the estimate is unavailable with revenue_quantity_missing in excludes. Max, latest, unique count, weighted sum and custom aggregations do not add a fixed amount per call, so their estimate is unavailable with non_additive_revenue_aggregation. When the estimate is unavailable, a margin policy decides with its on_unavailable value (allow, warn or deny), and policy.reason is economics_unavailable.

Which subscription is checked

Plan, entitlements, limits and usage all come from one subscription, and only subscriptions that are current at this moment count: started, not ended, and before their end date.

With subscription_id, /can evaluates that subscription of the customer. With entity_id, it evaluates the Entity’s own subscription, else the customer’s own subscription (not owned by an Entity). When both are sent, the subscription must belong to that Entity. An unknown or ended selection answers no_subscription.
Without either, /can evaluates the customer’s only current subscription. A customer with several current subscriptions is evaluated on its own subscription (not owned by an Entity) when there is exactly one. Otherwise the answer is allowed: false with the reason subscription_required: send subscription_id or entity_id. The newest subscription is never picked for you.

A customer with one current subscription sees no change. Usage is counted per subscription, so the usage of one Entity’s seat never counts against another subscription’s limit, and the counter continues across plan changes of the same subscription. POST /billing/upgrade selects the subscription the same way. For a customer with several current subscriptions it answers 409 subscription_required unless exactly one of them is the customer’s own.

Usage and billing periods

used follows the billing period in which Nozle invoices the usage, for every plan interval (weekly, monthly, quarterly, semiannual, yearly), for calendar and anniversary billing, and in the customer’s time zone (the customer’s, else its billing entity’s):

Periods start at midnight in that time zone. A weekly calendar period starts on Monday.
An anniversary subscription that starts on the 29th to the 31st starts on the last day of shorter months.
A yearly or semiannual plan that bills its charges monthly resets monthly.

A recurring Feature, such as seats or storage, keeps one running total across billing periods: a hard limit keeps blocking after a period ends instead of reopening on the first day. For these limits, a weighted sum or custom Feature counts the running sum of event values, not its time-weighted or custom billing value.

Denial reasons

A denial is an HTTP 200 response with allowed: false and one of these reason values:

`reason`	Meaning
`feature_not_found`	No feature with this code exists in the organization
`no_subscription`	The customer has no active subscription: none started, ended or cancelled, or the customer does not exist. Also an unknown or ended `subscription_id` or `entity_id`
`subscription_required`	The customer has several current subscriptions and not exactly one of them is the customer’s own (not Entity-owned). Send `subscription_id` or `entity_id`
`no_entitlement`	The customer’s plan does not include the feature
`usage_limit_exceeded`	A hard limit is reached. A soft limit never denies; it sets `overage` to `true`
`economic_policy_denied`	A margin policy in `deny` mode rejected the estimated cost or margin. The `policy` object has the detail

For example, an unknown feature code returns:

{
  "allowed": false,
  "reason": "feature_not_found",
  "used": 0,
  "limit": null,
  "remaining": null
}

SDK wrappers

Node:

nozle.can('cust_123', 'api_calls')

Python:

from nozle import Nozle

nozle = Nozle()  # reads NOZLE_SECRET_KEY

nozle.can('cust_123', 'api_calls')

React: fetch the result through your authenticated backend and pass it to FeatureGate, UsageGate, or your own UI.

Availability and freshness

If usage cannot be read reliably, the hosted API returns HTTP 503 with a structured error and request ID, without an access decision. Treat it as unavailable; do not convert the failure into allowed: true or zero usage. Use bounded retries within your request budget and retain the request ID for support. Entitlement configuration refresh is approximately once per minute. A plan or quota edit may take that interval to appear in can() results. Usage projections are asynchronous, and a separate can() followed by track() does not reserve quota atomically. Use Track and Consume Credits for atomic product-credit consumption.

Getting Started

Billing

Product Credits

Margin Intelligence

Entitlements

The can() Endpoint

Request

Response

Field reference

Runtime behavior

Which subscription is checked

Usage and billing periods

Denial reasons

SDK wrappers

Availability and freshness

​Request

​Response

​Field reference

​Runtime behavior

​Which subscription is checked

​Usage and billing periods

​Denial reasons

​SDK wrappers

​Availability and freshness

Request

Response

Field reference

Runtime behavior

Which subscription is checked

Usage and billing periods

Denial reasons

SDK wrappers

Availability and freshness