...
...
Purchasing
Endpoints overview
...
A user may purchase a License for themselves by calling the create license endpoint. In order to create a license, some method of payment must be provided. At the moment only one method of payment is supported: "billing". With this payment method, no further payment details are necessary, but the user is charged through the service provider's billing system.
Purchase restrictions
User restrictions
Some users may have restrictions set on their account that prevent them from making purchases. These users are marked with the user flag "LICENSE_PURCHASE_RESTRICTED". See [BSS] User flags for more information.
Product restrictions
Only Products marked as "visible" may be purchased through the License v4 API. Other Products should not be shown to users as purchasable options.
| Info |
|---|
In Channel API v2, products including a listed channel is included in the response under the "categories" field. The "visible" field shows whether the Product is considered "visible". The "price" field can be used to show the purchasing price of the product to the user. |
Idempotency
The purchasing endpoint requires an idempotency key to be present in the headers. The client should generate some adequately unique random value for this header, which should be sent along with the purchasing request. The purpose of this header is to prevent accidentally making multiple API calls to purchase the same product due to a connection error. If the request is made multiple times with the same idempotency key, then the API exhibits idempotent behavior, meaning it will return the same response as in the previous call without processing another purchase request. It is therefore safe to call the API multiple times if the response was lost, as long as the same idempotency key is used in subsequent requests.
| Warning |
|---|
The purchasing API does not restrict the user from purchasing a License for a Product even if they already have a License for the given Product. If different idempotency keys are used for purchasing, then multiple Licenses will be purchased for the user. |
Billing
If the service provider supports billing as a payment method, then they are responsible for handling the billing of the customer separately. A list of all purchased licenses can be obtained through the management API, see Management GetLicenses. The order ID of a license uniquely identifies each purchase. This identifier should be used to make sure the user is not billed multiple times for the same purchase.
Listing licenses and products
Endpoints overview
...
/api/license/v4/users/{user_id}/licenses
...
...
It is possible to show to the user existing licenses and filter them by status. Client can filter licenses on it's side by next attributes:
- status in [PROCESSING, CHECK_INVALID, ORDER_ERROR, ACTIVE, EXPIRED, SUSPENDED, SUSPENDEDADMIN]
- start_date - when the license was activated, in unix epoch timestamp
- end_date - when the license is going to be deactivated, in unix epoch timestamp
Every license object from returned list include product for which the license was issued
Client may obtain a list of products to combine with a list of licenses to show to the end-user.
Use cases
Let user select product and purchase it
With a call to 'Get all products' client can obtain a list of all visible and buyable (those products attributes could be changed through management license API) product objects which will look similar to
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"data": [
{
"id": "41",
"type": "Product",
"attributes": {
"title": "Sport channels meagpack",
"description": "Complete collection for all sports channels",
"type": "CHANNEL_GROUP",
"is_premium": true
},
"relationships": {
"live": {
"data": [
{
"id": "42",
"type": "Channel"
}
]
},
"catchup": {
"data": [
{
"id": "42",
"type": "Channel"
}
]
},
"npvr": {
"data": [
{
"id": "42",
"type": "Channel"
}
]
},
"startover": {
"data": [
{
"id": "42",
"type": "Channel"
}
]
}
}
}
]
} |
The 'type' attribute could be one of:
...
Value in API
...
Service description
...
The 'relationships' here are same as defined at Channel API. If the channel is listed in relationship section then this service for that channel is available.
...
Value in API
...
Service description
...
Having this data should be enough to represent available products and what channels and services those provide to user.
After user selected product he needs it can be purchased with request to 'Issue a license to a user' endpoint.
Allow user to view his licenses
When client can requests 'Get user licenses' endpoint response received contains all of user licenses and also includes all associated products. From here licenses could be combined with it's associated products by id, filtered by status (for example to show only active) and represented to end-user, those which are close to expire could be spotted via stop_date and marked with some warning.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
{
"data": [
{
"id": "42",
"type": "License",
"attributes": {
"status": "ACTIVE",
"start_date": 1523268666,
"stop_date": 1523268698
},
"relationships": {
"user": {
"data": {
"id": "41",
"type": "User"
}
},
"product": {
"data": {
"id": "41",
"type": "Product"
}
}
},
"links": {
"self": "https://boox.fi/api/user/waqqas.jabbar@gmail.com/license/10"
}
}
],
"included": [
{
"id": "41",
"type": "Product",
"attributes": {
"title": "Sport channels meagpack",
"description": "Complete collection fo all sports channels",
"type": "CHANNEL_GROUP",
"is_premium": true
},
"relationships": {
"live": {
"data": [
{
"id": "42",
"type": "Channel"
}
]
},
"catchup": {
"data": [
{
"id": "42",
"type": "Channel"
}
]
},
"npvr": {
"data": [
{
"id": "42",
"type": "Channel"
}
]
},
"startover": {
"data": [
{
"id": "42",
"type": "Channel"
}
]
}
}
}
]
} |
Migration from legacy
| Info | ||
|---|---|---|
| ||
...