> ## Documentation Index > Fetch the complete documentation index at: https://docs.metrifox.com/llms.txt > Use this file to discover all available pages before exploring further. # Get entitlements summary > Retrieve the full entitlements summary for a subscription, including configuration, allowances, carryover settings, and transition policy details The `metadata.policy` field is only present when the entitlement resulted from a plan transition (upgrade or downgrade). For entitlements that were part of the original subscription, this field will not be included. ## OpenAPI ````yaml GET /api/v1/subscriptions/{subscription_id}/v2/entitlements-summary openapi: 3.0.1 info: title: Metrifox API Documentation version: v1 description: >- Welcome to Metrifox Platform's API documentation. This comprehensive API suite enables seamless integration with our platform, providing secure and efficient access to our services. servers: - url: https://{defaultHost} variables: defaultHost: default: api.metrifox.com security: - api_key: [] paths: /api/v1/subscriptions/{subscription_id}/v2/entitlements-summary: get: tags: - Subscriptions summary: Get entitlements summary for a subscription description: > Retrieves the full entitlements summary for a specific subscription. Returns detailed configuration and state for each entitlement, including: - **Entitlement configuration**: feature type, usage model, pricing type, billing interval, aggregation method - **Allowances & limits**: purchased quantity, included allowance, usage limits, soft limit settings - **Carryover settings**: whether carryover is enabled, expiry rules, max carryover amounts - **Credit settings**: prepaid status, credit cost, credit source - **Metadata**: transition policy details (only present when the entitlement resulted from a plan upgrade or downgrade) This endpoint is useful for understanding the full entitlement configuration, including how quantities are allocated, billed, and carried over between billing periods. operationId: getSubscriptionEntitlementsSummary parameters: - name: subscription_id in: path required: true description: The unique subscription identifier (UUID) schema: type: string format: uuid example: 625f5cee-259b-4994-b7eb-416b9e551f2c responses: '200': description: Entitlements summary fetched successfully content: application/json: schema: $ref: '#/components/schemas/EntitlementSummaryResponse' examples: entitlements_summary: summary: Entitlements Summary Response value: statusCode: 200 message: Entitlements summary fetched successfully meta: {} data: - id: 120007eb-c6f7-4439-b7a9-75f09d60079e subscription_id: 625f5cee-259b-4994-b7eb-416b9e551f2c customer_id: fa545755-be20-4d1b-85d0-a2265dd52c56 tenant_id: 90321ce5-5d33-4f6d-a4eb-11660e2b6a46 customer_key: cust-mljp3ra6ffjm active: true subscription_item_id: b1d50e4f-85db-49d0-9d86-3b02e5f69414 purchased_qty: 2 billing_interval: monthly feature_key: feature_skills_audit soft_limit_enabled: false included_allowance: null included_allowance_reset_interval: none included_allowance_reset_anchor: subscription_start usage_limit: null usage_limit_reset_interval: none usage_limit_reset_anchor: subscription_start max_carryover_amount: null carryover_action: does_not_expire carryover_enabled: false event_names: null aggregation_method: sum feature_type: metered price_type: in_advance entitlement_id: 20910dfa-4a88-451c-9b85-2ed8ba937e97 prepaid: false prepaid_credit_system_id: null usage_model: per_use credit_cost: null created_at: '2026-02-13T13:01:29.875Z' updated_at: '2026-02-13T13:01:29.875Z' billing_interval_value: 1 credit_source_id: null carryover_expiry_interval: null carryover_expiry_value: null metadata: policy: id: null name: >- Metrifox Default Same Interval Plan Downgrade Policy timing: immediate tenant_id: null created_at: null updated_at: null change_type: downgrade time_policy: charge_strategy: partial_charge unused_time_strategy: partial_credit cycle_strategy: keep_existing_cycle consumable_policy: charge_strategy: issue_zero_credit_apply_full_charge provision_strategy: allocate_full_quantity unused_quantity_handling: roll_over unprovisioned_quantity_handling: do_nothing interval_strategy: same_interval billing_end_date: '2026-03-12T16:55:21.847Z' transitioning_subscription_id: c541c94a-6a02-4bc0-bf8b-1a5a4245e1d8 feature_name: Skills Audit - id: 2e7f7fd8-c723-4d7c-98e5-b8239ab5226e subscription_id: 625f5cee-259b-4994-b7eb-416b9e551f2c customer_id: fa545755-be20-4d1b-85d0-a2265dd52c56 tenant_id: 90321ce5-5d33-4f6d-a4eb-11660e2b6a46 customer_key: cust-mljp3ra6ffjm active: true subscription_item_id: 7ab84a13-f11d-4f03-9936-c5ece50bf40a purchased_qty: 3 billing_interval: monthly feature_key: feature_seats soft_limit_enabled: false included_allowance: null included_allowance_reset_interval: none included_allowance_reset_anchor: subscription_start usage_limit: null usage_limit_reset_interval: none usage_limit_reset_anchor: subscription_start max_carryover_amount: null carryover_action: does_not_expire carryover_enabled: false event_names: null aggregation_method: sum feature_type: metered price_type: in_advance entitlement_id: 262bd36c-eef8-4981-8c58-52c952d3f42e prepaid: false prepaid_credit_system_id: null usage_model: persistent_use credit_cost: null created_at: '2026-02-13T13:01:29.715Z' updated_at: '2026-02-13T13:01:29.715Z' billing_interval_value: 1 credit_source_id: null carryover_expiry_interval: null carryover_expiry_value: null metadata: policy: id: null name: >- Metrifox Default Same Interval Plan Downgrade Policy timing: immediate tenant_id: null created_at: null updated_at: null change_type: downgrade time_policy: charge_strategy: partial_charge unused_time_strategy: partial_credit cycle_strategy: keep_existing_cycle consumable_policy: charge_strategy: issue_zero_credit_apply_full_charge provision_strategy: allocate_full_quantity unused_quantity_handling: roll_over unprovisioned_quantity_handling: do_nothing interval_strategy: same_interval billing_end_date: '2026-03-12T16:55:21.847Z' transitioning_subscription_id: c541c94a-6a02-4bc0-bf8b-1a5a4245e1d8 feature_name: Seats errors: {} '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Subscription not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: statusCode: 404 message: Subscription not found errors: subscription_id: - >- Subscription with ID '625f5cee-259b-4994-b7eb-416b9e551f2c' does not exist x-codeSamples: - lang: python label: Python SDK source: > from metrifox_sdk import MetrifoxClient client = MetrifoxClient(api_key="your_api_key") # Get entitlements summary for a subscription subscription_id = "625f5cee-259b-4994-b7eb-416b9e551f2c" response = client.subscriptions.get_entitlements_summary(subscription_id) for entitlement in response['data']: print(f"Feature: {entitlement['feature_name']} ({entitlement['feature_key']})") print(f" Usage model: {entitlement['usage_model']}") print(f" Purchased qty: {entitlement['purchased_qty']}") print(f" Billing: {entitlement['billing_interval']}") print(f" Active: {entitlement['active']}") # Check if this entitlement resulted from a plan transition if entitlement.get('metadata', {}).get('policy'): policy = entitlement['metadata']['policy'] print(f" Transition: {policy['change_type']} ({policy['timing']})") - lang: javascript label: Javascript SDK source: > import { init } from "metrifox-js"; const metrifoxClient = init({ apiKey: process.env.METRIFOX_API_KEY }); // Get entitlements summary for a subscription const subscriptionId = "625f5cee-259b-4994-b7eb-416b9e551f2c"; const response = await metrifoxClient.subscriptions.getEntitlementsSummary(subscriptionId); response.data.forEach(entitlement => { console.log(`Feature: ${entitlement.feature_name} (${entitlement.feature_key})`); console.log(` Usage model: ${entitlement.usage_model}`); console.log(` Purchased qty: ${entitlement.purchased_qty}`); console.log(` Billing: ${entitlement.billing_interval}`); console.log(` Active: ${entitlement.active}`); // Check if this entitlement resulted from a plan transition if (entitlement.metadata?.policy) { const policy = entitlement.metadata.policy; console.log(` Transition: ${policy.change_type} (${policy.timing})`); } }); - lang: ruby label: Ruby SDK source: > require 'metrifox-sdk' # Initialize with configuration METRIFOX_SDK = MetrifoxSDK.init({ api_key: "your-api-key" }) # Get entitlements summary for a subscription subscription_id = "625f5cee-259b-4994-b7eb-416b9e551f2c" response = METRIFOX_SDK.subscriptions.get_entitlements_summary(subscription_id) response['data'].each do |entitlement| puts "Feature: #{entitlement['feature_name']} (#{entitlement['feature_key']})" puts " Usage model: #{entitlement['usage_model']}" puts " Purchased qty: #{entitlement['purchased_qty']}" puts " Billing: #{entitlement['billing_interval']}" puts " Active: #{entitlement['active']}" # Check if this entitlement resulted from a plan transition if entitlement.dig('metadata', 'policy') policy = entitlement['metadata']['policy'] puts " Transition: #{policy['change_type']} (#{policy['timing']})" end end components: schemas: EntitlementSummaryResponse: type: object properties: statusCode: type: integer example: 200 message: type: string example: Entitlements summary fetched successfully meta: type: object additionalProperties: true description: Additional metadata data: type: array items: $ref: '#/components/schemas/EntitlementSummary' description: Array of entitlement summary records errors: type: object additionalProperties: true description: Any errors that occurred ErrorResponse: type: object properties: message: type: string description: Error message errors: type: object additionalProperties: true description: Detailed error information EntitlementSummary: type: object properties: id: type: string format: uuid description: Unique entitlement summary identifier subscription_id: type: string format: uuid description: Associated subscription ID customer_id: type: string format: uuid description: Associated customer ID tenant_id: type: string format: uuid description: Tenant ID customer_key: type: string description: Customer key in your application active: type: boolean description: Whether the entitlement is currently active subscription_item_id: type: string format: uuid description: Associated subscription item ID purchased_qty: type: integer description: Quantity purchased billing_interval: type: string description: Billing interval (e.g., monthly, yearly) feature_key: type: string description: Unique key for the feature soft_limit_enabled: type: boolean description: Whether soft limits are enabled (allows overage) included_allowance: type: number nullable: true description: Included usage allowance (null if none) included_allowance_reset_interval: type: string description: How often the included allowance resets (e.g., none, monthly) included_allowance_reset_anchor: type: string description: Anchor point for the reset interval (e.g., subscription_start) usage_limit: type: number nullable: true description: Hard usage limit (null if unlimited) usage_limit_reset_interval: type: string description: How often the usage limit resets (e.g., none, monthly) usage_limit_reset_anchor: type: string description: Anchor point for the usage limit reset (e.g., subscription_start) max_carryover_amount: type: number nullable: true description: Maximum amount that can be carried over (null if unlimited) carryover_action: type: string description: What happens to unused quantity (e.g., does_not_expire, expires) carryover_enabled: type: boolean description: Whether carryover is enabled event_names: type: array nullable: true items: type: string description: Event names associated with this entitlement aggregation_method: type: string description: How usage is aggregated (e.g., sum, max, last) feature_type: type: string description: Type of feature (e.g., metered, boolean) price_type: type: string description: Pricing type (e.g., in_advance, in_arrears) entitlement_id: type: string format: uuid description: Reference to the entitlement definition prepaid: type: boolean description: Whether the entitlement is prepaid via credits prepaid_credit_system_id: type: string format: uuid nullable: true description: Credit system ID if prepaid usage_model: type: string description: Usage model (e.g., per_use, persistent_use) credit_cost: type: number nullable: true description: Credit cost per unit (null if not credit-based) created_at: type: string format: date-time description: When the entitlement summary was created updated_at: type: string format: date-time description: When the entitlement summary was last updated billing_interval_value: type: integer description: Numeric value for the billing interval (e.g., 1 for every 1 month) credit_source_id: type: string format: uuid nullable: true description: Credit source ID if applicable carryover_expiry_interval: type: string nullable: true description: Interval for carryover expiry (e.g., months, days) carryover_expiry_value: type: integer nullable: true description: Numeric value for carryover expiry metadata: allOf: - $ref: '#/components/schemas/EntitlementSummaryMetadata' nullable: true description: >- Additional metadata including transition policy details (when applicable) feature_name: type: string description: Human-readable name of the feature EntitlementSummaryMetadata: type: object nullable: true properties: policy: allOf: - $ref: '#/components/schemas/TransitionPolicy' nullable: true description: >- Transition policy details. Only present when the entitlement resulted from a plan upgrade or downgrade. billing_end_date: type: string format: date-time description: End date of the current billing period transitioning_subscription_id: type: string format: uuid description: ID of the subscription being transitioned from additionalProperties: true TransitionPolicy: type: object description: >- Policy applied during a plan transition (upgrade/downgrade). Only present when the entitlement resulted from a plan change. properties: id: type: string nullable: true description: Policy ID (null for default policies) name: type: string description: Name of the transition policy timing: type: string description: When the transition takes effect (e.g., immediate) tenant_id: type: string nullable: true description: Tenant ID (null for default policies) created_at: type: string format: date-time nullable: true description: Policy creation timestamp updated_at: type: string format: date-time nullable: true description: Policy last update timestamp change_type: type: string description: Type of plan change (e.g., upgrade, downgrade) time_policy: $ref: '#/components/schemas/TransitionTimePolicy' cycle_strategy: type: string description: How billing cycles are handled (e.g., keep_existing_cycle) consumable_policy: $ref: '#/components/schemas/TransitionConsumablePolicy' interval_strategy: type: string description: Interval strategy (e.g., same_interval) TransitionTimePolicy: type: object properties: charge_strategy: type: string description: Strategy for charging (e.g., partial_charge) unused_time_strategy: type: string description: Strategy for unused time (e.g., partial_credit) TransitionConsumablePolicy: type: object properties: charge_strategy: type: string description: >- Strategy for charging consumables (e.g., issue_zero_credit_apply_full_charge) provision_strategy: type: string description: Strategy for provisioning (e.g., allocate_full_quantity) unused_quantity_handling: type: string description: How unused quantity is handled (e.g., roll_over) unprovisioned_quantity_handling: type: string description: How unprovisioned quantity is handled (e.g., do_nothing) securitySchemes: api_key: type: apiKey name: x-api-key in: header ````