> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kelviq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve customer entitlements

> Retrieves detailed entitlement information for a customer.
- If `feature_id` is provided as a query parameter, returns details for that specific feature.
- If `feature_id` is omitted, returns all entitlements for the customer.


<Info>Click the base URL in the API playground and select the **Sandbox** host for test data or the **Production** host for live data. Use credentials from the same environment.</Info>


## OpenAPI

````yaml /api-reference/openapi.json get /entitlements/
openapi: 3.0.0
info:
  title: kelviq API
  version: 1.0.0
  description: >-
    API for interacting with kelviq services, derived from Python SDK
    documentation.
servers:
  - url: https://sandboxapi.kelviq.com/api/v1
    description: Sandbox — Test payments
  - url: https://api.kelviq.com/api/v1
    description: Production — Live payments
security:
  - bearerAuth: []
tags:
  - name: Products
    description: Catalog products.
  - name: Product Settings
    description: Per-product settings (currency, VPN/Tor/proxy, product URL).
  - name: Product Files
    description: Product images and downloadable assets.
  - name: Features
    description: Catalog features that can be granted as plan entitlements.
  - name: Plans
    description: Catalog plans (CRUD, publish, versions, prices).
  - name: Plan Entitlements
    description: Feature entitlements attached to a plan.
  - name: Plan Files
    description: Files attached to plans, and signed download links.
  - name: Media
    description: Generate presigned S3 upload URLs for product/plan images and files.
  - name: Partner
    description: Partner integration APIs (organization provisioning, lookup).
  - name: Charges
    description: >-
      One-time payments charged immediately against a customer's default payment
      method.
  - name: Refunds
    description: Full and partial refunds for paid orders.
  - name: Transactions
    description: >-
      Charges, refunds, disputes, and other financial movements for the
      authenticated organization.
  - name: Payment Methods
    description: Saved customer payment methods (cards, etc.).
  - name: Orders
    description: Completed and resolved orders for the authenticated organization.
  - name: Order Events
    description: Timeline events for a specific order.
  - name: Webhooks
    description: Delivery logs for webhook events sent to your configured endpoints.
  - name: Checkout Sessions
    description: Merchant-side view of checkout sessions created by customers.
  - name: Checkout Session Events
    description: Timeline events for a specific checkout session.
paths:
  /entitlements/:
    servers:
      - url: https://edge.sandboxapi.kelviq.com/api/v1
        description: Sandbox — Test environment
      - url: https://edge.api.kelviq.com/api/v1
        description: Production — Live environment
    get:
      tags:
        - Entitlements
      summary: Retrieve customer entitlements
      description: >
        Retrieves detailed entitlement information for a customer.

        - If `feature_id` is provided as a query parameter, returns details for
        that specific feature.

        - If `feature_id` is omitted, returns all entitlements for the customer.
      operationId: getCustomerEntitlements
      parameters:
        - name: customer_id
          in: query
          required: true
          description: The unique identifier for the customer.
          example: cust_123
          schema:
            type: string
        - name: feature_id
          in: query
          required: false
          description: >-
            Optional. The unique identifier for a specific feature. If provided,
            filters entitlements to this feature.
          example: advanced-analytics
          schema:
            type: string
      responses:
        '200':
          description: A list of entitlement details for the customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckEntitlementsResponse'
              examples:
                specificFeatureExample:
                  summary: Example for get_entitlement for a specific feature
                  value:
                    customerId: cust_456
                    entitlements:
                      - featureId: advanced-analytics
                        featureType: METER
                        hasAccess: true
                        resetAt: '2025-05-22 08:27:45'
                        hardLimit: false
                        usageLimit: 3
                        currentUsage: 0
                        remaining: 3
                allFeaturesExample:
                  summary: Example for get_all_entitlements for a customer
                  value:
                    customerId: cust_123
                    entitlements:
                      - featureId: advanced-analytics
                        featureType: METER
                        hasAccess: true
                        resetAt: '2025-05-22 08:27:45'
                        hardLimit: false
                        usageLimit: 3
                        currentUsage: 0
                        remaining: 3
                      - featureId: basic-reporting
                        featureType: FLAG
                        hasAccess: true
                        resetAt: null
components:
  schemas:
    CheckEntitlementsResponse:
      type: object
      properties:
        customerId:
          type: string
          example: cust_456
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/EntitlementDetail'
    EntitlementDetail:
      type: object
      properties:
        featureId:
          type: string
          example: advanced-analytics
        hasAccess:
          type: boolean
          example: true
        featureType:
          type: string
          example: METER
        resetAt:
          type: string
          description: >-
            The reset timestamp for the entitlement (e.g., yyyy-MM-dd HH:mm:ss).
            Not necessarily ISO 8601.
          example: '2025-05-22 08:27:45'
        hardLimit:
          type: boolean
          nullable: true
          example: false
        usageLimit:
          type: integer
          format: int32
          nullable: true
          example: 3
        currentUsage:
          type: integer
          format: int32
          nullable: true
          example: 0
        remaining:
          type: integer
          format: int32
          nullable: true
          example: 3
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The Server API Key obtained from the kelviq application. Pass as a
        Bearer token in the Authorization header. Example: 'Authorization:
        Bearer __YOUR_API_KEY__'

````