CONSUMPTION BASED LIMITATIONS

Consumption-based limitations are numerical quotas that are tracked over time. Typical examples include documents per month, API calls per day, or jobs per year.

In SLASCONE, limitations can generally be used in two ways:

• Static limitation: The limitation defines a fixed maximum value, regardless of actual usage patterns. For example, a license may allow up to 100 stored documents. In this case, the client application is responsible for enforcing compliance.
• Consumption-based limitation: The limitation defines a quota that is consumed over time and reset according to a defined rule. For example, a license may allow the creation of 10 documents per month. SLASCONE tracks the consumption and indicates whether quota is still available.

DEFINING A CONSUMPTION-BASED LIMITATION

Whether a limitation is static or consumption-based is defined in the license. For consumption-based limitations, you must also define how and when the quota resets.

• Entire Lifecycle: The quota applies across the entire lifetime of the license and does not reset automatically. This mode is typically used for trial scenarios or total-use quotas.
• Periodical (number of days): The quota resets every n days.
• First day of month, quarter, or year: The quota resets automatically on the first day of the next month, quarter, or year.

Goodwill

In many scenarios, it is useful to allow a small overconsumption margin. In SLASCONE, this can be configured as a percentage.

Example: a limitation of 10 combined with a goodwill of 20% allows a consumption of up to 12, but not more.

This is an edition property, not a license property.

Prevent Overusage

By default, SLASCONE enforces the configured limit. In that case, a consumption heartbeat fails when there is not enough quota left.

If you deactivate this behavior, consumption heartbeats may exceed the configured quota. This is useful for metering scenarios where usage should still be tracked even if the configured quota has already been reached.

This is an edition property, not a license property.

Aggregation Logic

By default, consumption heartbeats are additive. This means the consumption balance is calculated as the sum of all consumption heartbeats within the relevant period.

However, some metrics should not be treated additively. For values such as stock levels or inventory levels, only the latest reported value is relevant. In such cases, the newest heartbeat replaces the previous value instead of being added to it.

This is a product limitation property, not an edition or license property.

Deletion Logic

The behavior of assignment or user deletion depends on the context and role:

• Customer Portal user: deletion fails if there are any consumption heartbeats.
• Vendor-side deletion: deletion succeeds. In that case, all related consumption heartbeats are deleted and the consumption balance is recalculated.

CONSUMPTION ANALYSIS

In addition to enforcing consumption-based limitations, SLASCONE also provides visibility into how these limitations are actually used over time.

This helps both operational teams and product managers understand current balances, identify usage patterns, and detect unusual consumption early.

License Level

At the license level, SLASCONE provides a detailed view of the consumption history for a specific license. This is especially useful when you want to understand the exact state and usage of an individual customer or installation.

The following data is available:

• current balance
• consumption heartbeats as raw data
• a graphical representation of the consumption history

Product Level

SLASCONE also provides a broader view of consumption at the product level.

This allows product managers and operational teams to quickly identify overall trends across customers and monitor how consumption-based features are used in practice.

CONSUMPTION ALERTS

You can define multiple consumption alerts for the same edition and limitation.

For more information, see CONSUMPTION ALERTS.

CLIENT/API CONSIDERATIONS

In most scenarios, the recommended flow is:

1. check or reserve the consumption through SLASCONE
2. perform the local operation
3. roll back the consumption if the local operation fails

Consumption Heartbeat

Before starting a client action that affects a consumption-based limitation, the client should send a consumption heartbeat to SLASCONE:

POST /isv/{isv_id}/data_gathering/consumption_heartbeats

The response indicates whether sufficient quota is available.

• If there is not enough quota, the response contains a null transaction_id.
• If there is enough quota, the response contains a valid transaction_id.

With a valid transaction_id, the client can proceed with the relevant local operation, for example processing a document.

It is also possible to create a consumption directly in the Vendor Portal. This can be useful for testing purposes or when consumptions need to be added manually by the vendor.

External ID

When creating a consumption heartbeat, you can optionally send an external_id.

The external_id must be unique for the combination of limitation and client, or limitation and user. Sending a heartbeat with the same external_id overrides the previous value.

Typically, the external_id is a timestamp such as 20250329, representing the consumption of a specific time window. This helps prevent accidental double submission and simplifies client-side workflows.

Rollback

If the relevant local operation fails after the consumption heartbeat has been accepted, you should roll back the heartbeat to ensure that no quota is consumed for a failed operation.

POST /isv/{isv_id}/data_gathering/consumption_heartbeats/rollback

It is also possible to roll back a consumption directly in the Vendor Portal:

Validation

If you only want to check the remaining balance without writing a consumption heartbeat, you can use the following method:

POST /isv/{isv_id}/provisioning/validate/consumption

Use validation when you want to check the current balance without consuming quota. Use a consumption heartbeat when you are about to perform an operation that should actually consume quota.

OPERATIONAL BEHAVIOR OF COMMON CONFIGURATIONS

The following overview summarizes how common license configurations affect consumption limits, overusage behavior, rollbacks, and the effect of license changes.

Unlimited Mode

In Unlimited Mode, consumption is not restricted by a predefined limit.

• no limit is enforced and no remaining value is calculated
• consumption is still tracked, even though no remaining quota is calculated
• a rollback is always possible, regardless of resets
• when switching a license from Unlimited Mode to a limited mode, the change becomes visible in the consumption heartbeats after the next heartbeat

Unlimited Mode is typically used when unrestricted usage is required while still tracking overall consumption.

Prevent Overusage with Goodwill

This configuration allows controlled overusage by defining a goodwill buffer.

• consumption is allowed beyond the nominal limit, but only up to the configured goodwill threshold
• further overusage is blocked once the goodwill threshold has been reached
• a rollback is only possible if no reset has occurred since the original heartbeat
• switching the license to Unlimited Mode has no immediate effect on existing consumption entries
• other license changes also do not retroactively affect existing consumption entries

This setup is useful when limited overusage should be allowed within a defined tolerance.

Prevent Overusage without Goodwill

In this mode, consumption is strictly capped at the configured limit.

• usage is only allowed up to the defined limit
• no overusage is permitted
• a rollback is only possible if no reset has occurred since the original heartbeat
• license changes do not retroactively affect existing consumption entries

This option is suited for strict enforcement of contractual usage limits.

Prevent Overusage Disabled

In this configuration, a limit exists but is not enforced.

• consumption can exceed the configured limit
• overusage is tracked, but not blocked
• a rollback is only possible if no reset has occurred since the original heartbeat

This setup is useful when the configured limit should serve as a reference value for monitoring, reporting, or later billing, without blocking additional consumption.

User-Based Consumption

User provisioning can also consume licensed limits.

• if the user limit is set to 2, only two users can consume the respective limitation
• a third user is rejected once the limit is reached
• a rollback is always possible, regardless of resets

This mechanism helps ensure that licensed user counts are enforced consistently.