<< Introduction
< Previous Chapter: Manage Access Rights
2/ Retrieve Rights
All Rights for a Specific Customer
Typically used to retrieve a user’s rights when they log in.
GET /v1/Usages?ReferenceCustomer=cust-1
{
...
"Items": [
{
...
"IdSubscription": 10738,
"ReferenceSegment": "dev",
"ReferenceFeature": "f1",
"ReferenceCustomer": "cust-1",
"TypeFeature": "Limitation",
"QuantityIncluded": 3,
"QuantityCurrent": 4,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
},
{
...
"IdSubscription": 10738,
"ReferenceSegment": "dev",
"ReferenceFeature": "f2",
"ReferenceCustomer": "cust-1",
"TypeFeature": "Consumption",
"QuantityIncluded": 0,
"QuantityCurrent": 57,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
},
{
...
"IdSubscription": 10738,
"ReferenceSegment": "dev",
"ReferenceFeature": "f3",
"ReferenceCustomer": "cust-1",
"TypeFeature": "OnOff",
"IsIncluded": true,
"IsEnabled": true,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
]
}
All Rights for a Specific Feature
Typically used for bulk processing on the affected customers.
GET /v1/Usages?ReferenceFeature=f1
{
...
"Items": [
{
...
"IdSubscription": 4627,
"ReferenceSegment": "dev",
"ReferenceFeature": "f1",
"ReferenceCustomer": "cust-1",
"TypeFeature": "Limitation",
"QuantityIncluded": 1,
"QuantityCurrent": 1,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
},
...
]
}
Rights for a Specific Customer and Feature
Typically used to check rights in real-time and for In-App Purchases.
GET /v1/Usage?ReferenceCustomer=cust-1&ReferenceFeature=f1
{
...
"IdSubscription": 4627,
"ReferenceSegment": "dev",
"ReferenceFeature": "f1",
"ReferenceCustomer": "cust-1",
"TypeFeature": "Limitation",
"QuantityIncluded": 1,
"QuantityCurrent": 1,
"DatePeriodStart": "2016-03-29T21:35:32.00Z",
"DatePeriodEnd": "2016-04-29T21:35:32.00Z"
}
Interpretation
The Usage resource is generic, allowing it to be used for any type of rights, options, and billing rules. It is essential to understand what is returned in order to interpret it in your case.
Each call returns the type of Feature and the identifiers/references to determine the relevant Segment / Customer / Feature / Subscription.
A period is also returned (DatePeriodStart / DatePeriodEnd): this is the current period of the relevant subscription. In the case of consumption-type features, this indicates the date when the quota will be reset for the customer.
For an OnOff Feature
- IsIncluded (true|false) indicates if the feature is included for free in the subscription.
- IsEnabled (true|false) indicates if the feature is active.
Note that it is possible to have an included but inactive feature (e.g., a free option).
In the vast majority of cases, IsEnabled is the only relevant value. The activation price should not be considered here: refer to the article on In-App Purchases if your goal is to allow your customers to activate a paid option without going through the Customer Portal.
For Limitation and Consumption Features
- QuantityIncluded is the quantity included for free in the subscription.
- QuantityCurrent is the current quantity.
Note that QuantityIncluded can be greater than QuantityCurrent. For example, my Premium subscription entitles me to 3 users, which I can add at any time.
Similarly, QuantityCurrent can be greater than QuantityIncluded if the included quantity has been exceeded. For example, my Premium subscription entitles me to 3 users and charges me X€/month per additional user.
The price to increase or decrease quantities should not be considered here (the calculation can be quite complex). Consult the article on In-App Purchases if your goal is to allow your customers to increase a value without going through the Customer Portal.
No Rights, No Access
If the Customer has no rights, it means they have no active subscription. This situation can occur when the subscription is completed, canceled, when the customer has outstanding payments, or no longer has a valid payment method.
We recommend cutting off their access to your service and displaying the Customer Portal as an overlay. ProAbono will offer them, depending on the cases:
- To take out a new subscription
- To update their payment methods
- To settle outstanding payments
- To download their past invoices (even after cancellation, they may need them)
Insufficient Rights
The customer may have rights, but they are not sufficient. For example, their subscription does not grant them access to the Premium section, or they want to add a user but have already reached their quota.
In the case of increasing the quota, In-App Purchases is the best solution: the customer purchases additional users with a single click, directly from your service.
If in-app purchase is not applicable, you can suggest that they upgrade to a higher plan by redirecting them to the ‘Subscription’ section of your service.
It is also possible to offer an integrated upgrade, but the integration is more complex. Refer to the upgrade documentation for more information.
Next chapter: Adjusting Rights and Consumption >