This series of articles provides best practices for managing access rights to your service through ProAbono.
<< Introduction
< Previous Chapter: Retrieve Rights
3 / Adjust Rights and Consumption
The Usage resource allows you to retrieve and modify rights.
Single Modification
POST /v1/Usage
{
"ReferenceFeature": "f1",
"ReferenceCustomer": "cust-1",
"Increment": 5,
"DateStamp": "2016-03-29T19:33:50.65Z"
}
Multiple Modifications
POST /v1/Usages
[
{
"ReferenceFeature": "f1",
"ReferenceCustomer": "cust-1",
"QuantityCurrent": 12,
"DateStamp": "2016-03-29T19:33:50.65Z"
},
{
"ReferenceFeature": "f2",
"ReferenceCustomer": "cust-1",
"Increment": 3,
"DateStamp": "2016-03-29T19:33:50.65Z"
}
]
Note that the fields vary depending on the type of Feature.
The DateStamp Field
Each modification must be timestamped using the DateStamp field. It is necessary to avoid calculation and concurrent modification issues. This field is the date when the modification will be taken into account in the calculations. Note that it is not possible to schedule a future modification.
Rejected Modification
In some cases, the modification will be rejected. We strongly recommend handling all these cases to have a robust integration and prevent your sales or product managers from urgently contacting you.
| Reason | HTTP Status | Error Code |
|---|---|---|
| The customer has no active subscription or none of their active subscriptions contain this Feature | 403 | Error.Api.Usage.NoneMatching |
| The modification results in a payment, and the customer has no valid payment method | 403 | Error.Customer.PaymentSettings.Missing |
| The customer has outstanding payments | 403 | Error.Customer.Billing.CappingReached |
Accepted Modification
Depending on the subscription settings, a modification may increase the subscription cost and/or result in an extra charge on the next invoice. If the modification is related to a customer interaction in your service, it is strongly recommended to request validation from the customer and inform them about the impact on their next invoice. Refer to the ‘In-App Purchases‘ article for more information.