---
title: "Partial update of entitlements"
method: PATCH
path: "/plans/{plan_code}/entitlements"
tags: ["Entitlements"]
---

# Partial update of entitlements

`PATCH /plans/{plan_code}/entitlements`

## Request

- Base URL: `https://api-m.sandbox.paypal.com`
- URL: `https://api-m.sandbox.paypal.com/plans/{plan_code}/entitlements`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `/api/oauth-proxy` scopes: `read`, `write`
- TypeScript: <https://skmtc.dev/paypal/apis/usage-based-billing-api/docs/plans/:plan_code/entitlements/patch.ts> (a function with typed inputs; its response is checked against the schema)

Update privilege values for one or more plan entitlements. Any new privileges or features you provide will be added. Existing values are overwritten if duplicates are found. Items not included in the request will be left unchanged.

## Path parameters

- `plan_code` string, required

## Request body

- object
  - `entitlements` EntitlementRequest[], required
    - `feature_code` string, required: 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.
    - `feature_privilege_values` object, required: 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).

## Response `200`

Entitlements updated successfully

- PlanEntitlementListResponse
  - `entitlements` PlanEntitlementResponse[], required: List of entitlements associated with the plan
    - `feature_code` string, required: 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.
    - `name` string: Human-readable display name of the feature shown in user interfaces. More descriptive than the code and helps users understand the feature's purpose.
    - `description` string: 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.
    - `feature_privileges` PlanEntitlementPrivilege[], required: 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.
      - `code` string, required: Unique identifier for this specific privilege within the feature. Used as a key when setting privilege values.
      - `name` string: User-friendly display name for this privilege shown in interfaces. More descriptive than the code and helps users understand what this specific setting controls.
      - `value_type` 'STRING' | 'BOOLEAN' | 'INTEGER' | 'SELECT', required: 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.
      - `config` PrivilegeConfig: Additional configuration for privileges that require constraints or options. Currently used for 'select' type privileges to define allowed values.
        - `select_options` string[]: 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.
      - `value` unknown, required

## Other responses

- `400`: Bad Request - Invalid input data
- `404`: Resource Not Found.
- `422`: Bad Request - Invalid input data
- `500`: Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.dev/paypal/apis/usage-based-billing-api.md) - [All operations](https://skmtc.dev/paypal/apis/usage-based-billing-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paypal/apis/usage-based-billing-api/revisions/22fb46514ac4?raw)