---
title: "Create an entitlement"
method: POST
path: "/plans/{plan_code}/entitlements"
tags: ["Entitlements"]
---

# Create an entitlement

`POST /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/post.ts> (a function with typed inputs; its response is checked against the schema)

Assign a feature to a plan with specific privilege values. This action removes all current entitlements and replaces with the new ones provided. To retain existing entitlements while adding new ones, apply a PATCH request.

## 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 `201`

Entitlements created 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.
- `409`: Conflict - The request could not be completed due to a conflict with the current state of the resource.
- `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)