Update subscription entitlements

curl --request PATCH \
  --url https://api.getlago.com/api/v1/subscriptions/{external_id}/entitlements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entitlements": {
    "seats": {
      "max": 20,
      "max_admins": 10,
      "root": false
    },
    "sso": {
      "provider": "okta"
    }
  }
}
'

{
  "entitlements": [
    {
      "code": "seats",
      "name": "Number of seats",
      "description": "Number of users of the account",
      "privileges": [
        {
          "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"
            ]
          }
        }
      ],
      "overrides": {
        "max": 15,
        "provider": "okta"
      }
    }
  ]
}

Entitlements

Update subscription entitlements

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.

PATCH

subscriptions

{external_id}

entitlements

Update subscription entitlements

curl --request PATCH \
  --url https://api.getlago.com/api/v1/subscriptions/{external_id}/entitlements \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entitlements": {
    "seats": {
      "max": 20,
      "max_admins": 10,
      "root": false
    },
    "sso": {
      "provider": "okta"
    }
  }
}
'

{
  "entitlements": [
    {
      "code": "seats",
      "name": "Number of seats",
      "description": "Number of users of the account",
      "privileges": [
        {
          "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"
            ]
          }
        }
      ],
      "overrides": {
        "max": 15,
        "provider": "okta"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

external_id

string

required

External ID of the existing subscription

Example:

"5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba"

Body

application/json

Subscription entitlements payload

entitlements

object

required

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.

Show child attributes

entitlements.{key}

object

Privilege values for this feature. All privileges must exist on the feature.

Show child attributes

entitlements.{key}.{key}

Example:

{
  "seats": {
    "max": 20,
    "max_admins": 10,
    "root": false
  },
  "sso": { "provider": "okta" }
}

Response

Subscription entitlements updated

entitlements

object[]

required

Show child attributes

entitlements.code

string

required

Unique code used to identify the feature. Max 255 characters.

Example:

"seats"

entitlements.name

string | null

required

Name of the feature. Max 255 characters.

Example:

"Number of seats"

entitlements.description

string | null

required

Description of the feature. Max 600 characters.

Example:

"Number of users of the account"

entitlements.privileges

object[]

required

Privileges associated with this feature. Each privilege shows the plan value and any subscription override.

Show child attributes

entitlements.privileges.code

string

required

Unique code for the privilege.

Example:

"max"

entitlements.privileges.name

string | null

required

Display name for the privilege.

Example:

"Maximum"

entitlements.privileges.value_type

enum<string>

required

Data type of the privilege value. Default: string

Available options:

integer,

boolean,

string,

select

Example:

"integer"

entitlements.privileges.config

object

required

Show child attributes

entitlements.privileges.config.select_options

string[]

Array of string, required only when value_type is select.

Example:

["google", "okta"]

entitlements.privileges.value

required

Applicable value this this subscription (override_value if set, plan_value otherwise). Type depends on the privilege's value_type.

Example:

10

entitlements.privileges.plan_value

required

Value assigned to this privilege in the plan. Type depends on the privilege's value_type.

Example:

10

entitlements.privileges.override_value

required

Value assigned to this subscription specifically. Type depends on the privilege's value_type. Null if no override is set.

Example:

10

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"] }
  }
]

entitlements.overrides

object

required

Example:

{ "max": 15, "provider": "okta" }

The subscription entitlement object Delete a subscription entitlement

⌘I

API Reference

Authorizations

Path Parameters

Body

Response