accounting.charge¶
Records usage in the system
| Request | Response | Error |
|---|---|---|
BulkRequest<ChargeWalletRequestItem> |
BulkResponse<Boolean> |
CommonErrorMessage |
Internal UCloud services invoke this endpoint to record usage from a workspace. Providers report data
indirectly to this API through the outgoing Control API. This endpoint causes changes in the balances
of the targeted allocation and ancestors. UCloud will change the balance and localBalance property
of the targeted allocation. Ancestors of the targeted allocation will only update their balance.
UCloud returns a boolean, for every request, indicating if the charge was successful. A charge is successful if no affected allocation went into a negative balance.
📝 NOTE: Unsuccessful charges are still deducted in their balances.
The semantics of charge depends on the Product’s payment model.
Absolute:
UCloud calculates the change in balances by multiplying: the Product’s pricePerUnit, the number of units, the number of periods
UCloud subtracts this change from the balances
Differential:
UCloud calculates the change in balances by comparing the units with the current
localBalanceUCloud subtracts this change from the balances
Note: This change can cause the balance to go up, if the usage is lower than last period
Selecting Allocations¶
The charge operation targets a wallet (by combining the ProductCategoryId and WalletOwner). This means that the charge operation have multiple allocations to consider. We explain the approach for absolute payment models. The approach is similar for differential products.
UCloud first finds a set of leaf allocations which, when combined, can carry the full change. UCloud
first finds a set of candidates. We do this by sorting allocations by the Wallet’s chargePolicy. By
default, this means that UCloud prioritizes allocations that expire soon. UCloud only considers
allocations which are active and have a positive balance.
📝 NOTE: UCloud does not consider ancestors at this point in the process.
UCloud now creates the list of allocations which it will use. We do this by performing a rolling sum of the balances. UCloud adds an allocation to the set if the rolling sum has not yet reached the total amount.
UCloud will use the full balance of each selected allocation. The only exception is the last element, which might use less. If the change in balance is never reached, then UCloud will further charge the first selected allocation. In this case, the priority allocation will have to pay the difference.
Finally, the system updates the balances of each selected leaf, and all of their ancestors.
Examples: