> ## 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. # Create a feature > Creates a new feature that represents a capability or functionality that can be entitled to customers. Features are the building blocks of your entitlement system - they define what can be granted to customers and what aspects can be configured. Each feature can have multiple privileges that allow fine-grained control over its behavior (e.g., a 'seats' feature might have 'max' and 'max_admins' privileges). Once created, features can be assigned to plans with specific privilege values. ## OpenAPI ````yaml /api-reference/ubb_openapi_inline.json post /features 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: /features: post: tags: - Features summary: Create a feature description: >- Creates a new feature that represents a capability or functionality that can be entitled to customers. Features are the building blocks of your entitlement system - they define what can be granted to customers and what aspects can be configured. Each feature can have multiple privileges that allow fine-grained control over its behavior (e.g., a 'seats' feature might have 'max' and 'max_admins' privileges). Once created, features can be assigned to plans with specific privilege values. operationId: CreateFeature requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FeatureRequest' examples: BasicFeatureCreation: summary: Create a basic feature with integer and boolean privileges value: code: seats name: Number of seats description: Number of users allowed in the account privileges: - code: max name: Maximum seats value_type: INTEGER - code: max_admins name: Maximum admin users value_type: INTEGER - code: root name: Allow root user value_type: BOOLEAN FeatureWithSelectPrivilege: summary: >- Create a feature with a select-type privilege for predefined options value: code: sso name: Single Sign-On description: SSO authentication configuration privileges: - code: provider name: SSO Provider value_type: SELECT config: select_options: - google - okta - azure - saml - code: enabled name: SSO Enabled value_type: BOOLEAN responses: '201': description: >- Feature was successfully created and is now available for use in plan entitlements content: application/json: schema: $ref: '#/components/schemas/FeatureResponse' examples: BasicFeatureCreation: summary: Response for basic feature creation value: code: seats name: Number of seats description: Number of users allowed in the account privileges: - code: max name: Maximum seats value_type: INTEGER - code: max_admins name: Maximum admin users value_type: INTEGER - code: root name: Allow root user value_type: BOOLEAN created_at: '2025-01-28T10:00:00Z' FeatureWithSelectPrivilege: summary: Response for feature with select privilege value: code: sso name: Single Sign-On description: SSO authentication configuration privileges: - code: provider name: SSO Provider value_type: SELECT config: select_options: - google - okta - azure - saml - code: enabled name: SSO Enabled value_type: BOOLEAN created_at: '2025-01-28T10:00:00Z' '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/InternalServerError' components: schemas: FeatureRequest: type: object description: >- Request payload for creating a new feature. Features represent entitleable capabilities that can be assigned to customers through plans. required: - code allOf: - $ref: '#/components/schemas/FeatureBase' - type: object properties: privileges: type: array description: >- List of configurable privileges that define what aspects of this feature can be customized when creating entitlements. Each privilege can have different values assigned in different plans or subscriptions. Can be empty if the feature is simply on/off. items: $ref: '#/components/schemas/FeaturePrivilegeBase' FeatureResponse: type: object description: >- Complete feature object returned by the API, including all properties and server-generated fields like timestamps required: - code - created_at allOf: - $ref: '#/components/schemas/FeatureBase' - type: object properties: privileges: type: array description: Privileges associated with this feature. Can be empty items: $ref: '#/components/schemas/FeaturePrivilegeBase' created_at: allOf: - $ref: '#/components/schemas/DateTimeWithZone' description: >- Timestamp indicating when this feature was first created in the system. Used for audit and tracking purposes. FeatureBase: type: object description: >- Core properties that define a feature - a capability or functionality that can be entitled to customers through plans or subscriptions properties: code: type: string description: >- Unique identifier for the feature across your entire system. This code is used when creating entitlements and should represent the feature's function (e.g., 'seats', 'api-access', 'API_STORAGE'). Allows alphanumeric characters, underscores, and hyphens. maxLength: 255 pattern: ^[a-zA-Z0-9_-]+$ example: USER-SEATS name: type: string description: >- Customer-facing name of the feature that clearly describes what functionality or capability it provides. This name appears in billing interfaces and customer portals. maxLength: 255 example: Number of seats description: type: string description: >- Detailed explanation of what this feature provides, its limitations, and how it affects the customer's experience. maxLength: 600 example: Number of users allowed in the account FeaturePrivilegeBase: type: object description: >- Defines a configurable aspect of a feature that can be assigned different values when entitled to plans or subscriptions required: - code properties: code: type: string description: >- Unique identifier for the privilege within its parent feature. Used as a key when assigning values to this privilege in entitlements. Allows alphanumeric characters, underscores, and hyphens. maxLength: 255 pattern: ^[a-zA-Z0-9_-]+$ example: MAX-USERS name: type: string description: >- Human-friendly display name for the privilege shown in user interfaces. This helps users understand what aspect of the feature is being configured. maxLength: 255 example: Maximum seats value_type: $ref: '#/components/schemas/PrivilegeValueType' config: $ref: '#/components/schemas/PrivilegeConfig' DateTimeWithZone: type: string format: date-time description: Date and time in ISO 8601 format. example: '2023-10-01T12:00:00Z' Error: type: object properties: name: type: string debug_id: type: string message: type: string details: type: array items: $ref: '#/components/schemas/ErrorDetail' 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 ErrorDetail: type: object properties: field: type: string value: type: string location: type: string issue: type: string description: type: string 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. Forbidden: description: Authorization failed due to insufficient permissions. content: application/json: schema: $ref: '#/components/schemas/Error' example: name: NOT_AUTHORIZED message: Authorization failed due to insufficient permissions. debug_id: 565f78f101498 details: - issue: PERMISSION_DENIED description: >- You do not have permission to access or perform operations on this resource. Conflict: description: >- Conflict - The request could not be completed due to a conflict with the current state of the resource. 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: transaction_id issue: RESOURCE_ALREADY_EXISTS description: The resource identified by `field` already exists. 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 ````