Consuming from a Pool

No changes are required in how your application calls the License API. The same endpoints handle pooled and non-pooled licenses alike:

• POST /api/v4/add_consumption for licenses
• POST /api/v4/add_feature_consumption for product features

When the license or feature is linked to a pool, the pool accounting happens automatically on the server side.

What Happens on a Successful Consumption

For a pooled member, a successful call does two things atomically:

1. Increments the member's own total_consumptions (its individual contribution).
2. Increments the pool's total_consumptions (the shared balance).

The response includes both the member's state at the top level and a pool object reflecting the pool's post-write state. Your application always has the current shared balance without making additional calls:

{
  "id": 1790242270029099,
  "max_consumptions": 1234,
  "allow_unlimited_consumptions": false,
  "allow_negative_consumptions": true,
  "allow_overages": false,
  "max_overages": 0,
  "reset_consumption": false,
  "consumption_period": null,
  "total_consumptions": 3,
  "pool": {
    "id": 8,
    "name": "AI Credits",
    "type": "license",
    "total_consumptions": 8203,
    "max_consumptions": 10000,
    "allow_overages": true,
    "max_overages": 123,
    "allow_unlimited_consumptions": false,
    "allow_negative_consumptions": true
  }
}

The top-level fields always reflect the member's own values. The pool's values appear only inside the pool object.

Limit Enforcement

A pooled consumption is checked against both the member's cap and the pool's quota. The request fails on whichever limit is reached first:

• Member cap: The member's own max_consumptions, unless the member has unlimited consumptions enabled. The standard license and feature consumption error codes apply here.
• Pool quota: The pool's max_consumptions, extended by max_overages when overages are allowed. A max_overages value of 0 with overages enabled means no upper limit on overages.

When the pool's quota is exhausted, the call returns:

{
  "status": 400,
  "code": "pool_quota_exhausted",
  "message": "The consumption pool has no quota left."
}

Error Codes Reference

Code	When it occurs
pool_quota_exhausted	The pool has no remaining quota
invalid_pool_type	The member and pool types do not match (returned when linking via the Management API)

Negative Consumptions

When the pool allows negative consumptions (the default), passing a negative value to consumptions reduces both the member's counter and the pool's total. Neither counter drops below zero.

Concurrency

Multiple members can consume against the same pool concurrently. The pool balance is updated under row-level locks, ensuring totals remain accurate under parallel load. Your application does not need to serialize calls or implement any additional locking.

Offline Devices

A device that activated a pooled license offline consumes locally against units it reserved at activation time, then syncs its actual usage when it reconnects. See Offline Checkouts for the full lifecycle.