> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update subscription entitlements > This endpoint performs partial updates to subscription entitlements. The entitlements in the request are combined with existing entitlements associated with the subscription (even the ones inherited from plan) that are not mentioned in the request. ## OpenAPI ````yaml /api-reference/ubb_openapi_inline.json patch /subscriptions/{external_subscription_id}/entitlements openapi: 3.0.1 info: title: Usage Based Billing API version: 1.0.0 description: An Orchestrator for Usage Based Billing and Payments servers: - url: https://api-m.sandbox.paypal.com/v1/commerce/billing security: - BearerAuth: - read - write tags: - name: Alerts description: API endpoints for managing subscription alerts - name: Events description: API endpoints for managing events - name: Metrics description: API endpoints for metrics and usage data - name: Merchant Activation description: API endpoint for merchant activation - name: Credit Notes description: API endpoints for credit notes management - name: Customers description: API endpoints for customer management - name: Invoices description: API endpoints for invoice management - name: Plans description: API endpoints for subscription plans - name: Subscriptions description: API endpoints for subscriptions - name: Wallets description: API endpoints for wallet management - name: Taxes description: API endpoints for tax management - name: Billing Entities description: API endpoints for billing entities - name: Features description: API endpoints for managing features and privileges - name: Entitlements description: API endpoints for managing plan and subscription entitlements paths: /subscriptions/{external_subscription_id}/entitlements: patch: tags: - Entitlements summary: Update subscription entitlements description: >- This endpoint performs partial updates to subscription entitlements. The entitlements in the request are combined with existing entitlements associated with the subscription (even the ones inherited from plan) that are not mentioned in the request. operationId: UpdateSubscriptionEntitlements parameters: - name: external_subscription_id in: path required: true description: The external ID of the subscription schema: type: string requestBody: required: true content: application/json: schema: type: object properties: entitlements: type: array items: $ref: '#/components/schemas/EntitlementRequest' required: - entitlements example: entitlements: - feature_code: seats feature_privilege_values: max: 250 max_admins: 25 guest_access: true - feature_code: sso feature_privilege_values: provider: saml responses: '200': description: Entitlements updated successfully content: application/json: schema: $ref: '#/components/schemas/SubscriptionEntitlementListResponse' example: entitlements: - feature_code: seats name: Number of seats description: Number of users of the account feature_privileges: - code: max name: Maximum value_type: INTEGER value: 250 plan_value: 100 override_value: 250 - code: max_admins name: Max Admins value_type: INTEGER value: 25 plan_value: 10 override_value: 25 - code: root name: Allow root user value_type: BOOLEAN value: true plan_value: true override_value: null - code: guest_access name: Allow guest access value_type: BOOLEAN value: true plan_value: false override_value: true - feature_code: sso name: Single Sign-On description: SSO authentication configuration feature_privileges: - code: enabled name: SSO Enabled value_type: BOOLEAN value: true plan_value: true override_value: null - code: provider name: SSO Provider value_type: SELECT value: saml plan_value: google override_value: saml config: select_options: - google - okta - azure - saml '400': $ref: '#/components/responses/BadRequest' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' components: schemas: EntitlementRequest: type: object required: - feature_code - feature_privilege_values properties: feature_code: type: string description: >- Unique code used to identify the feature across the system. This serves as the primary identifier when assigning entitlements to plans and must be unique. maxLength: 255 pattern: ^[a-zA-Z0-9_-]+$ example: USER-SEATS feature_privilege_values: type: object description: >- Object mapping privilege codes to their assigned values for this entitlement. Each key is a privilege code (e.g., 'max_users', 'api_rate_limit'), and each value is what you want to set for that privilege (e.g., 100, true, 'premium'). The value type must match what's expected for that privilege (integer, boolean, or string/select). example: rate_limit: 1000 endpoints: all SubscriptionEntitlementListResponse: type: object required: - entitlements properties: entitlements: type: array description: >- List of effective entitlements for the subscription, showing both plan values and subscription-specific overrides items: $ref: '#/components/schemas/SubscriptionEntitlementResponse' SubscriptionEntitlementResponse: allOf: - $ref: '#/components/schemas/PlanEntitlementResponse' - type: object properties: feature_privileges: type: array description: >- Collection of privilege settings with both plan values and subscription-specific overrides. Each privilege shows the effective value applied to this subscription, with details about which values come from the plan and which are overridden. items: $ref: '#/components/schemas/EntitlementPrivilegeOverride' Error: type: object properties: name: type: string debug_id: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' PlanEntitlementResponse: type: object required: - feature_code - feature_privileges properties: feature_code: type: string description: >- Unique code used to identify the feature across the system. This serves as the primary identifier when assigning entitlements to plans and must be unique. maxLength: 255 pattern: ^[a-zA-Z0-9_-]+$ example: USER-SEATS name: type: string description: >- Human-readable display name of the feature shown in user interfaces. More descriptive than the code and helps users understand the feature's purpose. maxLength: 255 example: Number of seats description: type: string description: >- Comprehensive explanation of what this feature provides to customers, how it works, and any important usage information. This helps users understand the value and functionality of the feature. maxLength: 600 example: Number of users of the account feature_privileges: type: array description: >- Collection of configurable privilege settings associated with this feature entitlement. Each privilege defines a specific capability, setting, or limit (e.g., maximum users, access level, enabled/disabled status) that can be assigned values in the plan. These privileges determine what capabilities customers receive with this feature. items: $ref: '#/components/schemas/PlanEntitlementPrivilege' EntitlementPrivilegeOverride: type: object required: - value - plan_value - override_value allOf: - $ref: '#/components/schemas/EntitlementPrivilegeBase' - type: object properties: value: description: >- The effective value for this privilege that will be applied. This is the final value after considering both plan and override values. example: 15 plan_value: description: >- The default value from the subscription's plan. This value applies when no override is set. example: 10 override_value: description: >- The subscription-specific override value, if one exists. If null, the plan value is being used. example: 15 ErrorDetail: type: object properties: field: type: string value: type: string location: type: string issue: type: string description: type: string PlanEntitlementPrivilege: type: object required: - value allOf: - $ref: '#/components/schemas/EntitlementPrivilegeBase' - type: object properties: value: description: >- The specific value assigned to this privilege in the plan. The type of value must match the value_type field. For integer types, this represents numeric limits (e.g., 100 users); for boolean types, true/false settings (e.g., enable/disable features); for string or select types, specific configuration options (e.g., 'premium', 'basic'). example: 100 EntitlementPrivilegeBase: type: object required: - code - value_type properties: code: type: string description: >- Unique identifier for this specific privilege within the feature. Used as a key when setting privilege values. maxLength: 255 pattern: ^[a-zA-Z0-9_-]+$ example: max name: type: string description: >- User-friendly display name for this privilege shown in interfaces. More descriptive than the code and helps users understand what this specific setting controls. maxLength: 255 example: Maximum value_type: $ref: '#/components/schemas/PrivilegeValueType' config: $ref: '#/components/schemas/PrivilegeConfig' PrivilegeValueType: type: string description: >- Defines the data type that this privilege accepts when being assigned values in entitlements. 'INTEGER' for numeric limits, 'BOOLEAN' for on/off toggles, 'STRING' for text values, 'SELECT' for predefined options. enum: - STRING - BOOLEAN - INTEGER - SELECT default: STRING example: INTEGER PrivilegeConfig: type: object description: >- Additional configuration for privileges that require constraints or options. Currently used for 'select' type privileges to define allowed values. properties: select_options: type: array description: >- Defines the allowed values when value_type is 'select'. When creating entitlements, only these predefined options can be assigned. Useful for features like SSO providers, regions, or service tiers. items: type: string example: - google - okta - azure responses: BadRequest: description: Bad Request - Invalid input data content: application/json: schema: $ref: '#/components/schemas/Error' example: name: INVALID_REQUEST message: >- Request is not well-formed, syntactically incorrect, or violates schema. debug_id: dc99e3955cdd8 details: - field: /email value: abc location: body issue: INVALID_PARAMETER_VALUE description: The value of a field does not conform to the expected format. NotFound: description: Resource Not Found. content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableEntity: description: Bad Request - Invalid input data content: application/json: schema: $ref: '#/components/schemas/Error' example: name: UNPROCESSABLE_ENTITY message: >- The requested action could not be performed, semantically incorrect, or failed business validation. debug_id: 90957fca61718 details: - field: /email value: sdfwdj@sdfs.com location: body issue: UNSUPPORTED_EMAIL description: The email provided is not supported. InternalServerError: description: Internal Server Error - An unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/Error' example: name: INTERNAL_SERVER_ERROR message: An internal server error has occurred. debug_id: 90957fca61718 securitySchemes: BearerAuth: type: oauth2 description: >- Use the /v1/oauth2/token endpoint to obtain an access token and pass it as a Bearer token in the Authorization header. flows: clientCredentials: tokenUrl: https://api-m.sandbox.paypal.com/v1/oauth2/token scopes: read: Read access write: Write access ````