Subscriptions

In Q2 of 2021, Ultimaker introduces several subscription levels for software services and support. This guide explains how you can make your API integration aware of these subscriptions in order to deliver a better user experience.

By having different levels of subscriptions, Ultimaker can offer different functionality to different types of customers. This means that on the API level, not all functionality is available to all users. If you are building an integration that makes use of functionality that is somehow restricted in some subscription levels we advice you to implement a strategy to check for the subscription level before doing any API calls, as these calls might fail if the user does not have the right level.

Feature step-up

There are several feature step-up strategies in place that you should consider when building an integration:

• Unlimited: features like adding and managing 3D printers are unrestricted for all types of customers.
• Limited: features like digital library projects are available for "Personal" and "Essentials" users in limited form. For example, they can only create up to 5 private projects. For "Personal" we also do not allow project commenting, tagging and more.
• Unavailable: features like direct API access and Federated Single Sign-On are only available to "Excellence" customers. This restriction does not apply to commercial integration partners because we have a different business model for those integrations.

The exact limitations might change over time, but we advice to set up a business model for your integration that roughly matches the description above in order to create a consistent experience for users.

Info

Currently it is not possible to fetch the exact level of access of all features that a user has access to. This will be added in a future API update.

Checking subscriptions

You can find every active subscription for a user in their OAuth2 token. This usually looks like this:

{
    "user_id": "",
    ...
    "subscriptions": [
        {
            "level": 20,
            "plan_id": "standard",
            "type_id": "customer.support"
        },
        {
            "level": 20,
            "plan_id": "professional",
            "type_id": "customer.enterprise"
        }
    ],
    ...
}

• level: An integer number representing the relative level of the subscription compared to other levels.
• plan_id: The identifier of the subscription plan (essentials (10), professional (20) or excellence (30) for enterprise features, light (10), standard (20) or advanced (30) for the service & support level).
• type_id: The identifier of the subscription type (customer.enterprise or customer.support).

Info

Only one subscription per type can be active at a time. Usually this is a matching combination (i.e. the same level) of enterprise and support features.

Info

Users that do not belong to a workspace that has a subscription level, but do have at least one Ultimaker printer connected to their Digital Factory, are also eligible for certain extra features. While this is technically not a subscription level (as there is no payment involved), we call this "Ultimaker Personal".

API responses

If you hit a feature step-up limit that has been implemented on API level, you might get a response like this:

"HTTP/1.1 402 Payment Required"

{
    "errors": [
        {
            "id": "6e1f4de4-b0da-4d28-89a1-e6a9f7aa894b",
            "code": "insufficientSubscriptionPlan",
            "http_status": "402",
            "title": "your current subscription is not sufficient.",
            "meta": {
                "current_subscriptions": [
                    {
                        "level": 10,
                        "plan_id": "essentials",
                        "type_id": "customer.enterprise"
                    }
                ],
                "minimum_subscription": {
                    "level": 20,
                    "plan_id": "professional",
                    "type_id": "customer.enterprise"
                },
                "error_type": "AuthError"
            }
        }
    ]
}

The current_subscriptions field indicates the current subscriptions that the user has. The minimum_subscription field indicates the minimum subscription level needed to perform the operation.

Info

If you want to point your users to a solution for this error you can link to ultimaker.com/software/enterprise-software. On this page, users will be able to compare all the subscription plans and start upgrading.