User license V4

Introduction

This section describes user communication with AminoTV License v4 API. See User License API specification for details.

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 "is_buyable" may be purchased through the License v4 API.

Only products marked as "is_visible"  should be shown to users as purchasable options.

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.

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

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. The state machine below explains what products will be returned for GetAllProducts:

Use cases

Let user select product and purchase it

With a call to 'GetAllProducts' 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

{
  "data": [
    {
      "id": "41",
      "type": "Product",
      "attributes": {
        "title": "Sport channels meagpack",
        "description": "Complete collection for all sports channels",
		"is_premium": true,
		"price_record": {
	  		"amount": 98,
	  		"currency": "EUR"
		}
      },
      "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 '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.

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 'PurchaseUserLicense' endpoint.

Allow user to view his licenses

When client can requests 'GetUserLicenses' 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.

{
  "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"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "41",
      "type": "Product",
      "attributes": {
        "title": "Sport channels meagpack",
        "description": "Complete collection fo all sports channels",
        "is_premium": true,
		"price_record": {
	  		"amount": 98,
	  		"currency": "EUR"
		}
      },
      "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

Legacy endpoints 'api/user/<email>/license' and '/api/user/<email>/product'  replaced with '/api/license/v4/users/{user_id}/licenses'.