Execute user upgrades and downgrades

Your user seat type event-handling endpoint extracts key information for you to consider in determining whether to grant users membership to your plan. The logic you implement (for example, in a ServiceNow flow or internal application) determines whether to approve or deny the user membership to your plan.

This article reviews the type of event data available to use in your decision workflow and then demonstrates how to user plan upgrades and downgrades, using Smartsheet APIs.

Prerequisites

System Admin permissions. You must be a System Admin to upgrade or downgrade users.

Data for user membership logic

Here are some key data items available from each user seat type update event:

User ID: The unique integer identifying the user affected by the update.
Email address: The affected user's email address.
Seat type: The status of the user with respect to your plan. Here are the valid values:
- VIEWER
- GUEST
- PROVISIONAL_MEMBER
- MEMBER
Is internal? This is true if the affected user's email address belongs to a domain associated with your Smartsheet plan. Otherwise, it is false.

Use the above data in your decision-making logic (such as rules, workflows, and more). Then take action, such as upgrading or downgrading the user, or take action in Admin Center.

After your internal approval process is complete and a decision is made (e.g., license approved, user provisioned), you may call a specific Smartsheet API that we will provide. This API call requires Smartsheet system admin permissions.

Upgrade users

The Upgrade user operation upgrades the user's seat type within your Smartsheet organization or plan to a licensed Member or Guest.

Note: This operation is only available to system admins.

Upgrade eligibility

The operation applies to users with the following roles:

Provisional Member (to Member)
Viewer (to Member or Guest)
Guest (to Member)

If upgraded to Member: The user is granted full access permissions available to licensed Members, including the ability to create, edit, and comment on sheets, reports, dashboards, and workspaces.

If upgraded to Guest (for external users): The user is granted the maximum permissions available to Guests, including the ability to edit, and comment on sheets, reports, dashboards, and workspaces but not the ability to create assets.

Note:
If the user is already at the requested license level, the API returns a 200 OK.
If the user is deactivated, the API returns a 400 Bad Request error with a message suggesting that you reactivate the user before upgrading.

Upgrade scenarios:

Current Status	Requested Status	Upgrade Permitted?	Notes
Viewer	Member	Yes
Viewer	Guest	Yes
Guest	Member	Yes
Guest	Guest	No	Already at the permission level
Deactivated	Any	No	Admin must reactivate first
Member	Any	No	No further upgrade possible

Example: User upgrade

Here's how you can call the POST /users/{userId}/plans/{planId}/upgrade operation using a cURL command in your terminal.

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "smartsheet-integration-source: APPLICATION,YOUR_ORGANIZATION,YOUR_APP_NAME" \
  -H "Content-Type: application/json" \
  -d '{
    "seatType": "MEMBER"
}' \
  https://api.smartsheet.com/2.0/users/{userId}/plans/{planId}/upgrade

Replace the following placeholders with your values.

"MEMBER": For your seateType value, either leave it as "MEMBER" or set it to "GUEST" (for external users only).
{userId}: ID of the user to upgrade.
{planId}: Your plan's ID. You can access your plan ID in Admin Center by clicking on your profile icon in the top-right corner. See the Admin Center Overview for details.
YOUR_TOKEN_HERE: Your API access token (key).
YOUR_ORGANIZATION: Name of your company or organization.
YOUR_APP_NAME: Your app's name.

Downgrade users

Calling the Downgrade user endpoint allows you to downgrade a user to Guest or Viewer and eliminate that user from membership consideration.

Important: A downgraded user can no longer qualify for Provisional Member status. Granting the user membership requires a System Admin to explicitly make that user a member (or invite that user to become a member).

Note: This operation is only available to system admins.

The operation downgrades a user's seat type within your Smartsheet organization or plan from a licensed Member, Provisional Member, or Guest to a non-licensed Viewer or Guest role.

Viewer Role: The user retains view-only access to shared items but loses all editing, commenting, and creation capabilities.

Guest Role (for external users): The external user retains the ability to edit and comment on shared assets but loses the ability to create assets.

Note: Downgrading a user does not unshare them from assets, but it removes the user's ability to edit, comment on, and create assets, even if the user had access to them.

Downgrade eligibility

The user must be in an Active state and must currently be a Member, Provisional Member, or Guest. If the user has any other status (e.g., already a Viewer), the API will return a 400 Bad Request error. Below is a table of user statuses, including the permitted downgrades and the expected future status.

Current Status	Requested Status	Downgrade Permitted?	Notes
Member	Viewer	Yes
Member	Guest	Yes
Provisional Member	Viewer	Yes
Provisional Member	Guest	Yes
Guest	Viewer	Yes
Guest	Guest	No	Already at permission level
Deactivated	Any	No	Admin must reactivate first
Viewer	Any	No	No downgrade option exists. The user may be deactivated or removed.

Example: User downgrade

Here's how you can call the POST /users/{userId}/plans/{planId}/downgrade operation using a cURL command in your terminal.

curl -X POST \
  'https://api.smartsheet.com/2.0/users/{userId}/plans/{planId}/downgrade' \
  -H 'Authorization: Bearer YOUR_TOKEN_HERE' \
  -H 'Content-Type: application/json' \
  -H 'smartsheet-integration-source: APPLICATION,YOUR_ORGANIZATION,YOUR_APP_NAME' \
  -d '{
    "seatType": "VIEWER"
  }'