The enterprise quota system is authoritative for applied limits and usage.
The enterprise quota system is authoritative for applied limits and usage. QwenWork sets an absolute member limit; the enterprise system enforces it and returns the actual result.
All quota amounts are nonnegative decimal integer strings in credit_minor: 10000 minor = 1 credit, with a maximum of 9223372036854775807. Do not return JSON numbers, floating-point values or negative amounts.
This guide uses a synthetic scenario: a member limit of 500 credits, 70 used, 430 remaining, and an organization total of 1000 credits. The current product accepts only integer credit limits with a minimum of 500. A lower minimum from Query quota rules and period does not relax product validation.
See Quick start and Error handling for common headers and errors.
Provide every field above; only maximum_allowance may be null. Do not enable the extension if billing periods or limit enforcement are unavailable.
Explicitly return null values when no configuration exists:
HTTP 200 must return the applied response from Query member quotas, with organization, user, binding, revision, allowance, validity, cycle_id and expires_at matching this write. The successful query example above is the acknowledgement for this write. Return success only after the enterprise service has applied the change and it can be read back.
Retries for the same organization and write intent use the same idempotency key. The enterprise service must avoid executing the same write twice and must not treat a duplicate as a new top-up. QwenWork does not promise exactly-once execution or cross-system transactions. A timeout does not mean the enterprise service did not execute the write. Mismatched acknowledgements are failures and follow the existing retry flow.
Units and validity
All quota amounts are nonnegative decimal integer strings in credit_minor: 10000 minor = 1 credit, with a maximum of 9223372036854775807. Do not return JSON numbers, floating-point values or negative amounts.
This guide uses a synthetic scenario: a member limit of 500 credits, 70 used, 430 remaining, and an organization total of 1000 credits. The current product accepts only integer credit limits with a minimum of 500. A lower minimum from Query quota rules and period does not relax product validation.
| validity | expires_at | Meaning |
|---|---|---|
| permanent | null | A permanent limit configuration; consumption is still measured by billing cycle |
| current_cycle | RFC3339 timestamp | Valid for the current cycle; expiration is an exclusive boundary |
Query quota rules and period
No request body or query parameters. QwenWork uses this endpoint to read the configurable range and current period; it does not return the real-time organization balance.
| Field | Type | Requirement |
|---|---|---|
| organization_id | string | Exactly matches the requested organization |
| unit / scale | string / integer | Fixed at credit_minor / 10000 |
| minimum_allowance | string | Minimum accepted limit |
| maximum_allowance | string or null | At least minimum; null means no known configuration ceiling, not unlimited member quota |
| cycle_id | string | Nonempty identifier for the current cycle |
| cycle_start / cycle_end | RFC3339 string | Inclusive start, exclusive end; end strictly later than start |
| metering_mode | string | Fixed at periodic_ceiling |
| updated_at | RFC3339 string | Quota context update time |
Query member quotas
This is a read-only POST. The request contains 1–200 distinct external user IDs. Return one result per ID in request order, without omissions.
HTTP 200：
| Field | Type | Requirement when applied |
|---|---|---|
| external_user_id | string | Matches the corresponding request ID verbatim |
| status | string | applied, not_configured or not_found |
| binding_id | string | Nonempty; from the applied Set member limit request |
| applied_revision | integer | Applied revision, greater than 0 |
| allowance / used / remaining | string | Actual limit, usage and remaining amount, all in minor units |
| validity / cycle_id | string | Validity type and nonempty cycle ID |
| expires_at | string or null | Consistent with the validity type |
| updated_at | RFC3339 string | Actual quota update time |
| error_code | null | Successful items must not contain an error code |
Use not_found when the user does not exist, without fabricating a zero quota. Organization authorization failures must return HTTP 403. A queued target revision that has not executed must not be reported as applied.
The SDK provides explicit queries, but product quota dispatch does not require a read-after-write call to Query member quotas. Do not treat local configuration or a dispatch acknowledgement as a real-time query result.
Set member limit
Each request contains exactly one member. QwenWork dispatches quota changes in the background and retries failures through its existing mechanism. This is not a top-up request: do not add allowance to the previous limit or reset usage.
Complete request example, using the terminal variables from Quick start; execute only for a test member:
| Request field | Type | Requirement |
|---|---|---|
| binding_id | string | Nonempty binding identifier supplied by the caller; echo verbatim |
| items | array | Exactly one item |
| items[].external_user_id | string | External user ID in the current organization |
| items[].desired_revision | integer | Target revision greater than 0 |
| items[].allowance | string | Absolute limit in minor units |
| items[].validity | string | permanent or current_cycle |
| items[].cycle_id | string | Quota cycle for this write |
| items[].expires_at | string or null | null for permanent; expiration time for current_cycle |
Query organization quota
No request body or query parameters, and no member identity mapping is required. QwenWork reads this endpoint when querying organization quota; it does not derive the result from member quotas or historical statistics.
All three fields are required. The organization must match the request; allowance and used are minor-unit integer strings. The example represents a total of 1000 credits with 70 used. used may exceed allowance to report actual overuse. Unknown values must produce an error, not nulls, omitted fields or fabricated zeros.
Query organization quota returns real-time data, while Query organization usage overview returns a historical snapshot. They need not return identical values at different times. A 404 does not mean the extension is disabled and does not trigger a fallback to a default quota.