Lago Entitlements API

openapi: 3.2.0
info:
  title: Lago API documentation Entitlements API
  description: Lago API allows your application to push customer information and metrics (events) from your application to the billing application.
  version: 1.55.0
  license:
    name: AGPLv3
    url: https://github.com/getlago/lago-openapi/blob/main/LICENSE
  contact:
    email: tech@getlago.com
servers:
- url: https://api.getlago.com/api/v1
  description: US Lago cluster
- url: https://api.eu.getlago.com/api/v1
  description: EU Lago cluster
security:
- bearerAuth: []
tags:
- name: Entitlements
  description: Everything about Entitlement collection
  externalDocs:
    description: Find out more
    url: https://getlago.com/docs/api-reference/entitlements/plan-entitlements/plan-entitlement-object
paths:
  /plans/{code}/entitlements:
    parameters:
    - name: code
      in: path
      description: Code of the existing plan.
      required: true
      schema:
        type: string
        example: startup
    post:
      tags:
      - Entitlements
      summary: Create an entitlement
      description: This endpoint creates new entitlements by adding features to a plan. Note that all existing entitlements will be deleted and replaced by the ones provided. Sending an empty `entitlements` object, or omitting the key, therefore removes every entitlement of the plan. To add a new entitlement without removing the existing ones, use PATCH. The feature must exist and all privileges must be valid for the feature.
      operationId: createEntitlement
      requestBody:
        description: Entitlement payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdateInput'
        required: true
      responses:
        '200':
          description: Entitlement created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlements'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      tags:
      - Entitlements
      summary: List all entitlements
      description: This endpoint retrieves all entitlements for a specific plan.
      operationId: findAllEntitlements
      responses:
        '200':
          description: List of entitlements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlements'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Entitlements
      summary: Partial update of an entitlement
      description: This accepts a list of entitlements to update. If the feature isn't part of the plan yet, it's added with all the privileges from the payload. If the feature is already part of the plan, the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints.
      operationId: updateEntitlement
      requestBody:
        description: Entitlement payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdateInput'
        required: true
      responses:
        '200':
          description: Entitlement updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlements'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /plans/{code}/entitlements/{feature_code}:
    parameters:
    - name: code
      in: path
      description: Code of the existing plan.
      required: true
      schema:
        type: string
        example: startup
    - name: feature_code
      in: path
      description: Code of the existing feature.
      required: true
      schema:
        type: string
        example: seats
    get:
      tags:
      - Entitlements
      summary: Retrieve an entitlement
      description: This endpoint retrieves a specific entitlement for a plan.
      operationId: findEntitlement
      responses:
        '200':
          description: Entitlement
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Entitlements
      summary: Delete an entitlement
      description: This endpoint deletes an existing entitlement by removing the feature from the plan.
      operationId: destroyEntitlement
      responses:
        '200':
          description: Entitlement deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /plans/{code}/entitlements/{feature_code}/privileges/{privilege_code}:
    parameters:
    - name: code
      in: path
      description: Code of the existing plan.
      required: true
      schema:
        type: string
        example: startup
    - name: feature_code
      in: path
      description: Code of the existing feature.
      required: true
      schema:
        type: string
        example: seats
    - name: privilege_code
      in: path
      description: Code of the privilege to remove from the entitlement.
      required: true
      schema:
        type: string
        example: max_admins
    delete:
      tags:
      - Entitlements
      summary: Remove a privilege from an entitlement
      description: This endpoint removes a specific privilege and its value from an entitlement. The privilege remains untouched on the original feature.
      operationId: removeEntitlementPrivilege
      responses:
        '200':
          description: Entitlement with privilege removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlanEntitlement'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{external_id}/entitlements:
    parameters:
    - name: external_id
      in: path
      description: External ID of the existing subscription
      required: true
      schema:
        type: string
        example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    get:
      tags:
      - Entitlements
      summary: List all subscription entitlements
      description: This endpoint retrieves all entitlements for a specific subscription, including both plan entitlements and any subscription-specific overrides.
      operationId: findAllSubscriptionEntitlements
      parameters:
      - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: List of subscription entitlements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlements'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Entitlements
      summary: Update subscription entitlements
      parameters:
      - $ref: '#/components/parameters/subscription_status'
      description: This accepts a list of entitlements to update. If the feature isn't part of the subscription yet, it's added with all the privileges from the payload. If the feature is already part of the subscription (via plan or via override), the privilege and values are updated or added. All privileges must be valid for the feature. All features and privileges not part of the payload are left untouched. To remove privileges or features, use the DELETE endpoints.
      operationId: updateSubscriptionEntitlements
      requestBody:
        description: Subscription entitlements payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EntitlementUpdateInput'
        required: true
      responses:
        '200':
          description: Subscription entitlements updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlements'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /subscriptions/{external_id}/entitlements/{feature_code}:
    parameters:
    - name: external_id
      in: path
      description: External ID of the existing subscription
      required: true
      schema:
        type: string
        example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    - name: feature_code
      in: path
      description: Code of the existing feature
      required: true
      schema:
        type: string
        example: seats
    delete:
      tags:
      - Entitlements
      summary: Remove an entitlement from a subscription
      description: This endpoint removes a specific feature entitlement from a subscription. The plan keeps the feature and other subscriptions are not affected, but this subscription stops getting it. It returns the full list of entitlements remaining on the subscription.
      operationId: destroySubscriptionEntitlement
      parameters:
      - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Remaining subscription entitlements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlements'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{external_id}/entitlements/{feature_code}/privileges/{privilege_code}:
    parameters:
    - name: external_id
      in: path
      description: External ID of the existing subscription
      required: true
      schema:
        type: string
        example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
    - name: feature_code
      in: path
      description: Code of the existing feature.
      required: true
      schema:
        type: string
        example: seats
    - name: privilege_code
      in: path
      description: Code of the privilege to remove from the subscription entitlement override.
      required: true
      schema:
        type: string
        example: max_admins
    delete:
      tags:
      - Entitlements
      summary: Remove a privilege from a subscription entitlement override
      description: This endpoint removes a specific privilege from a subscription entitlement. The plan keeps the privilege and other subscriptions are not affected, but this subscription stops getting it. It returns the full list of entitlements remaining on the subscription.
      operationId: destroySubscriptionEntitlementPrivilege
      parameters:
      - $ref: '#/components/parameters/subscription_status'
      responses:
        '200':
          description: Remaining subscription entitlements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionEntitlements'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Bad Request error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorBadRequest'
    NotFound:
      description: Not Found error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorNotFound'
    UnprocessableEntity:
      description: Unprocessable entity error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnprocessableEntity'
    Unauthorized:
      description: Unauthorized error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiErrorUnauthorized'
  schemas:
    SubscriptionEntitlementObject:
      type: object
      required:
      - code
      - name
      - description
      - privileges
      - overrides
      properties:
        code:
          type: string
          example: seats
          description: Unique code used to identify the feature. Max 255 characters.
        name:
          type:
          - string
          - 'null'
          example: Number of seats
          description: Name of the feature. Max 255 characters.
        description:
          type:
          - string
          - 'null'
          example: Number of users of the account
          description: Description of the feature. Max 600 characters.
        privileges:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionEntitlementPrivilegeObject'
          example:
          - code: max
            name: Maximum
            value_type: integer
            config: {}
            value: 15
            plan_value: 10
            override_value: 15
          - code: max_admins
            name: Max Admins
            value_type: integer
            config: {}
            value: 5
            plan_value: 5
            override_value: null
          - code: root
            name: Allow root user
            value_type: boolean
            config: {}
            value: true
            plan_value: true
            override_value: null
          - code: provider
            name: SSO Provider
            value_type: select
            value: okta
            plan_value: google
            override_value: okta
            config:
              select_options:
              - google
              - okta
          description: Privileges associated with this feature. Each privilege shows the plan value and any subscription override.
        overrides:
          type: object
          additionalProperties: true
          example:
            max: 15
            provider: okta
          description: Privilege values set on this subscription only. Each key is a privilege code and each value is the subscription override. Privileges that use the plan value are not listed.
    PlanEntitlementPrivilegeObject:
      allOf:
      - $ref: '#/components/schemas/FeaturePrivilegeObject'
      - type: object
        required:
        - value
        properties:
          value:
            oneOf:
            - type: integer
              description: Value for integer type privileges
            - type: boolean
              description: Value for boolean type privileges
            - type: string
              description: Value for string or select type privileges
            example: 10
            description: Value assigned to this privilege in the entitlement. Type depends on the privilege's value_type.
    ApiErrorUnprocessableEntity:
      type: object
      required:
      - status
      - error
      - code
      - error_details
      properties:
        status:
          type: integer
          format: int32
          example: 422
        error:
          type: string
          example: Unprocessable entity
        code:
          type: string
          example: validation_errors
        error_details:
          type: object
    ApiErrorNotFound:
      type: object
      required:
      - status
      - error
      - code
      properties:
        status:
          type: integer
          format: int32
          example: 404
        error:
          type: string
          example: Not Found
        code:
          type: string
          example: object_not_found
    FeaturePrivilegeObject:
      type: object
      required:
      - code
      - name
      - value_type
      - config
      properties:
        code:
          type: string
          example: max
          description: Unique code for the privilege.
        name:
          type:
          - string
          - 'null'
          example: Maximum
          description: Display name for the privilege.
        value_type:
          type: string
          enum:
          - integer
          - boolean
          - string
          - select
          example: integer
          description: Data type of the privilege value. It defaults to `string`.
        config:
          type: object
          description: Extra configuration of the privilege. It is empty unless the value type is `select`.
          properties:
            select_options:
              type: array
              items:
                type: string
              example:
              - google
              - okta
              description: The values the privilege accepts. It is only sent when the value type is `select`.
    ApiErrorUnauthorized:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: integer
          format: int32
          example: 401
        error:
          type: string
          example: Unauthorized
    ApiErrorBadRequest:
      type: object
      required:
      - status
      - error
      properties:
        status:
          type: integer
          format: int32
          example: 400
        error:
          type: string
          example: Bad request
    EntitlementUpdateInput:
      type: object
      properties:
        entitlements:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              oneOf:
              - type: integer
              - type: boolean
              - type: string
            description: Privilege values for this feature. All privileges must exist on the feature.
          example:
            seats:
              max: 20
              max_admins: 10
              root: false
            sso:
              provider: okta
          description: Feature entitlements with their privilege values. Each key is a feature code, and the value is an object containing privilege codes with their associated values. The key is optional and defaults to an empty object. On the replacing endpoints (POST) an omitted or empty object removes every entitlement. On the partial update endpoints (PATCH) it changes nothing.
    PlanEntitlements:
      type: object
      required:
      - entitlements
      properties:
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/PlanEntitlementObject'
    PlanEntitlementObject:
      type: object
      required:
      - code
      - name
      - description
      - privileges
      properties:
        code:
          type: string
          example: seats
          description: Unique code used to identify the feature. Max 255 characters.
        name:
          type:
          - string
          - 'null'
          example: Number of seats
          description: Name of the feature. Max 255 characters.
        description:
          type:
          - string
          - 'null'
          example: Number of users of the account
          description: Description of the feature. Max 600 characters.
        privileges:
          type: array
          items:
            $ref: '#/components/schemas/PlanEntitlementPrivilegeObject'
          example:
          - code: max
            name: Maximum
            value_type: integer
            config: {}
            value: 10
          - code: max_admins
            name: Max Admins
            value_type: integer
            config: {}
            value: 5
          - code: root
            name: Allow root user
            value_type: boolean
            config: {}
            value: true
          - code: provider
            name: SSO Provider
            value_type: select
            value: google
            config:
              select_options:
              - google
              - okta
          description: Privileges associated with this feature. Each privilege must have a value assigned.
    PlanEntitlement:
      type: object
      required:
      - entitlement
      properties:
        entitlement:
          $ref: '#/components/schemas/PlanEntitlementObject'
    SubscriptionEntitlementPrivilegeObject:
      allOf:
      - $ref: '#/components/schemas/FeaturePrivilegeObject'
      - type: object
        required:
        - value
        - plan_value
        - override_value
        properties:
          value:
            oneOf:
            - type: integer
              description: Value for integer type privileges
            - type: boolean
              description: Value for boolean type privileges
            - type: string
              description: Value for string or select type privileges
            example: 10
            description: Applicable value for this subscription (override_value if set, plan_value otherwise). Type depends on the privilege's value_type.
          plan_value:
            oneOf:
            - type: integer
              description: Value for integer type privileges
            - type: boolean
              description: Value for boolean type privileges
            - type: string
              description: Value for string or select type privileges
            - type: 'null'
              description: No plan value set
            example: 10
            description: Value assigned to this privilege in the plan. Type depends on the privilege's value_type. Null when the privilege only exists as a subscription override.
          override_value:
            oneOf:
            - type: integer
              description: Value for integer type privileges
            - type: boolean
              description: Value for boolean type privileges
            - type: string
              description: Value for string or select type privileges
            - type: 'null'
              description: No override value set
            example: 10
            description: Value assigned to this subscription specifically. Type depends on the privilege's value_type. Null if no override is set.
    SubscriptionEntitlements:
      type: object
      required:
      - entitlements
      properties:
        entitlements:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionEntitlementObject'
  parameters:
    subscription_status:
      name: subscription_status
      in: query
      description: 'Filter by subscription status. When provided, the subscription is looked up with this status instead of the default `active` status. Possible values are `pending`, `active`, `terminated`, `canceled`, or `incomplete`.

        '
      required: false
      schema:
        type: string
        enum:
        - pending
        - active
        - terminated
        - canceled
        - incomplete
        default: active
        example: active
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
externalDocs:
  description: Lago Github
  url: https://github.com/getlago
x-provenance:
  method: harvested
  publisher: Lago
  source: https://getlago.com/api/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)