GEgetlago
entitlements

Update subscription entitlements

Changed on

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

Request

Query parameters

subscription_status'pending' | 'active' | 'terminated' | 'canceled' | 'incomplete'
Example:active

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.

Request body

entitlementsobject

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.

Example request

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

Response

Subscription entitlements updated

Example response

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

Changes

  • 5d26657495a3Revision changes
    • breaking

      response property entitlements/items/privileges/items/allOf[subschema #2]/plan_value list-of-types was widened by adding types null to media type application/json of response 200

    • info

      added the new enum value incomplete to the query request parameter subscription_status

    • info

      the request property became optional