This series of articles gives the best practices to integrate ProAbono. Pass it on to your technical team if you want a perennial integration that allows you to create offers and subscriptions on the fly without technical assistance.
<< Chapter 1
< Previous chapter: Recovering rights by API
Chap 4. Adjusting rights and consumption by API
The Usage resource allows you to recover rights, but also to modify them. The name of this resource comes from the Usage billing: it allows you to manage not only rights but also variable amount billing. The Uses are the values of the Characteristics in a Subscription.
Please note: the Usage resource cannot be used to modify a non-started subscription. If your goal is to create a custom subscription, you must use Subscription override.
One-time 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" } ]
The fields and answers are described in the API documentation. Note that the fields are different depending on the type of Feature.
The DateStamp field
Each modification must be time-stamped using the DateStamp field. This is necessary to avoid problems with calculations and concurrent modifications. This field is the date on which the modification will be taken into account in the calculations. Note that it is not possible to program a modification in the future.
Rejected modification
In some cases the modification will be rejected. We strongly recommend to manage all these cases, in order to have a robust integration and to avoid that your sales people or your product managers ask you in emergency.
Motif | Status HTTP | Error Code |
---|---|---|
Customer does not have an active subscription or none of its active subscriptions contain this feature | 403 | Error.Api.Usage.NoneMatching |
The modification leads to a payment and the customer does not have a valid means of payment | 403 | Error.Customer.PaymentSettings.Missing |
The customer has unpaid invoices | 403 | Error.Customer.Billing.CappingReached |
Modification accepted
Depending on the subscription settings, a change may result in an increase in the cost of the subscription and/or an extra charge on the next invoice. If the change is related to a customer interaction in your service, it is strongly recommended to ask the customer to validate the change and indicate the impact on the next invoice. See the ‘Integrated Purchase‘ article for more information.