> ## Documentation Index > Fetch the complete documentation index at: https://docs.meteroid.com/llms.txt > Use this file to discover all available pages before exploring further. # Check customer entitlement > Whether the customer may consume `requested` more of a feature right now, given their entitlement, the hard budgets that count the feature's usage, and their prepaid credit. Boolean features answer from their enabled state; config features grant access and return their `value`. An `ALLOW` limit never refuses: `in_overage` tells when the requested units go beyond it. Sliding windows send no threshold webhooks. Pass the group as `group[]=`: it is required when the entitlement is grouped. Pass `subscription_id` when the usage belongs to one subscription, so that a hard budget on another subscription does not refuse it. The answer reflects usage up to `as_of`: typically less than a minute old, and less than 10 seconds old once `near_limit` is true. A hard limit can therefore be exceeded by the usage of those few seconds. While `near_limit` is true, check before every request with its actual `requested` and do not cache the answer; `retry_after_ms` says when to check again. Use the check to gate access, not to bill. Beta: the request and response shapes of this endpoint may change before general availability. ## OpenAPI ````yaml https://api.meteroid.com/api-docs/openapi.json get /api/v1/customers/{id_or_alias}/entitlements/{feature_id_or_code}/check openapi: 3.1.0 info: title: meteroid description: '' license: name: LicenseRef-Proprietary identifier: LicenseRef-Proprietary version: 0.1.0 servers: [] security: [] tags: - name: Meteroid description: Meteroid API - name: Add-ons - name: Batch Jobs - name: Budgets description: >- Beta: may change before general availability. Spending limits on a customer's usage, or one subscription's, per currency, with alerts at percentages of the amount. x-beta: true - name: Checkout Sessions - name: Checks description: >- Beta: may change before general availability. Whether a customer may consume more of a feature right now. x-beta: true - name: Connect description: Manage connected accounts (Express & Standard) - name: Coupons - name: Credit Notes - name: Credit units description: >- Custom denominations, such as "credits", that usage can be priced in and credit granted or sold in, instead of money. - name: Credits description: >- Prepaid credit: a customer's wallets, credit grants, ledger and top-ups. Promotional credit applies before tax like a discount; paid credit applies after tax like a payment. - name: Custom Properties - name: Customers - name: Entitlements - name: Events - name: Features - name: Invoices - name: Licenses description: >- Licenses for your customers' self-hosted installations: signed tokens carrying their plan's entitlements, activated and refreshed by the installation over the public licensing endpoints. - name: Metrics - name: OAuth description: OAuth 2.0 token endpoints (public, client-credentials auth) - name: OAuth Apps description: Manage OAuth applications for Connect integrations - name: Plans - name: Product Families - name: Products - name: Subscriptions - name: Usage - name: Usage costs description: >- Beta: may change before general availability. A customer's or a subscription's usage events and usage over time, with what they cost. x-beta: true - name: Webhook Endpoints description: Manage outbound webhook endpoints and inspect their deliveries paths: /api/v1/customers/{id_or_alias}/entitlements/{feature_id_or_code}/check: get: tags: - Checks summary: Check customer entitlement description: >- Whether the customer may consume `requested` more of a feature right now, given their entitlement, the hard budgets that count the feature's usage, and their prepaid credit. Boolean features answer from their enabled state; config features grant access and return their `value`. An `ALLOW` limit never refuses: `in_overage` tells when the requested units go beyond it. Sliding windows send no threshold webhooks. Pass the group as `group[]=`: it is required when the entitlement is grouped. Pass `subscription_id` when the usage belongs to one subscription, so that a hard budget on another subscription does not refuse it. The answer reflects usage up to `as_of`: typically less than a minute old, and less than 10 seconds old once `near_limit` is true. A hard limit can therefore be exceeded by the usage of those few seconds. While `near_limit` is true, check before every request with its actual `requested` and do not cache the answer; `retry_after_ms` says when to check again. Use the check to gate access, not to bill. Beta: the request and response shapes of this endpoint may change before general availability. operationId: check_entitlement parameters: - name: id_or_alias in: path description: Customer ID or alias required: true schema: type: string - name: feature_id_or_code in: path description: Feature ID or code required: true schema: type: string - name: requested in: query description: Units the customer is about to consume. Defaults to 1. required: false schema: type: string format: decimal - name: subscription_id in: query description: >- The subscription (`sub_…`) the usage belongs to: only its own budgets and the customer-wide ones apply. Without it, a budget on one subscription refuses only once every subscription charging the feature's metric is refused by its own budget. required: false schema: type: string - name: group in: query description: >- The group to check, as `group[]=`: required when the entitlement is grouped required: false schema: type: object additionalProperties: type: string propertyNames: type: string style: deepObject explode: true responses: '200': description: Whether the customer may consume the requested units content: application/json: schema: $ref: '#/components/schemas/EntitlementCheck' '400': description: >- Invalid request, a group value is missing, or the subscription is not the customer's content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '404': description: Customer or feature not found content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' '503': description: Usage could not be read in time; retry shortly content: application/json: schema: $ref: '#/components/schemas/RestErrorResponse' security: - bearer_auth: [] components: schemas: EntitlementCheck: type: object description: Whether a customer may consume more of a feature now. required: - feature - has_access - reason - as_of - lag_ms - exact - near_limit - limits - in_overage properties: as_of: type: string format: date-time description: When the usage behind the answer was measured. exact: type: boolean description: 'Always false: the answer reflects usage up to `as_of`.' feature: $ref: '#/components/schemas/EntitlementCheckFeature' has_access: type: boolean in_overage: type: boolean description: >- The entitlement allows overage (`ALLOW`) and the requested units go beyond its limit: access is granted, and the overage is billed. lag_ms: type: integer format: int64 description: Age of that usage, in milliseconds. limit: type: - string - 'null' format: decimal limits: type: array items: $ref: '#/components/schemas/EntitlementCheckLimit' description: >- Deprecated: always empty. Customer-specific limits are entitlement overrides, reported in `used`, `limit` and `remaining`. near_limit: type: boolean description: >- True when a hard limit is within 5% of being reached, reached, or refuses the request. While true, check before every request with its actual `requested`, and do not cache an answer that grants access. period: oneOf: - $ref: '#/components/schemas/EntitlementCheckPeriod' description: The current period of the entitlement's limit. - type: 'null' reason: $ref: '#/components/schemas/EntitlementCheckReason' remaining: type: - string - 'null' format: decimal description: >- Units left before the limit, grace excluded: 0 while `has_access` is true when usage is within the grace allowance. retry_after_ms: type: - integer - 'null' format: int64 description: >- When to check again, in milliseconds. After a refusal by a limit whose period ends within 24 hours: the time until it ends (a smaller `requested` may still be allowed sooner); absent after a refusal by a sliding window, whose usage leaves it gradually. While `near_limit` is true and access is granted: 1000. used: type: - string - 'null' format: decimal description: >- `used`, `limit`, `remaining` and `period` report the entitlement's limit. Absent when the entitlement has no limit. value: oneOf: - $ref: '#/components/schemas/ConfigValue' description: The value of a `CONFIG` feature. - type: 'null' RestErrorResponse: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string EntitlementCheckFeature: type: object required: - id - code properties: code: type: string id: $ref: '#/components/schemas/FeatureId' EntitlementCheckLimit: type: object description: >- Deprecated: customer usage limits were replaced by entitlement overrides; never returned. required: - usage_limit_id - behavior - used - limit - remaining - has_access properties: behavior: $ref: '#/components/schemas/EntitlementCheckLimitBehavior' group: type: - object - 'null' description: The group the limit was evaluated for, when the limit is grouped. additionalProperties: type: string propertyNames: type: string has_access: type: boolean limit: type: string format: decimal remaining: type: string format: decimal usage_limit_id: $ref: '#/components/schemas/UsageLimitId' used: type: string format: decimal EntitlementCheckPeriod: type: object required: - start properties: end: type: - string - 'null' format: date-time description: Absent when the period never ends. start: type: string format: date-time EntitlementCheckReason: type: string enum: - WITHIN_LIMIT - LIMIT_REACHED - NO_ENTITLEMENT - DISABLED - BUDGET_EXCEEDED - INSUFFICIENT_BALANCE - TOO_MANY_GROUPS ConfigValue: oneOf: - $ref: '#/components/schemas/NumberConfigValue' - $ref: '#/components/schemas/BooleanConfigValue' - $ref: '#/components/schemas/TextConfigValue' - $ref: '#/components/schemas/JsonConfigValue' description: >- A static, typed configuration value carried by a Config entitlement. Resolved synchronously through the entitlement hierarchy — no metric, no usage counter. discriminator: propertyName: kind mapping: BOOLEAN: '#/components/schemas/BooleanConfigValue' JSON: '#/components/schemas/JsonConfigValue' NUMBER: '#/components/schemas/NumberConfigValue' TEXT: '#/components/schemas/TextConfigValue' ErrorCode: type: string enum: - BAD_REQUEST - NOT_FOUND - CONFLICT - FORBIDDEN - UNAUTHORIZED - TOKEN_EXPIRED - TOO_MANY_REQUESTS - INTERNAL_SERVER_ERROR FeatureId: type: string format: MeteroidId examples: - feat_7n42DGM5Tflk9n8mt7Fhc7 EntitlementCheckLimitBehavior: type: string enum: - TRACK - SOFT - HARD UsageLimitId: type: string format: MeteroidId examples: - ulim_7n42DGM5Tflk9n8mt7Fhc7 NumberConfigValue: type: object description: A number config value (decimal, encoded as a string). required: - value - kind properties: kind: type: string enum: - NUMBER value: type: string format: decimal BooleanConfigValue: type: object description: A boolean config value. required: - value - kind properties: kind: type: string enum: - BOOLEAN value: type: boolean TextConfigValue: type: object description: A text config value. required: - value - kind properties: kind: type: string enum: - TEXT value: type: string JsonConfigValue: type: object description: >- A structured (JSON) config value — the "metadata" case, several fields in one entitlement. required: - value - kind properties: kind: type: string enum: - JSON value: {} securitySchemes: bearer_auth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.