Management license

VMX integration is not supported within this API

Introduction

This section describes BSS communication with AminoTV License v4 API. Products and user licenses are manageable through License Management API.

The license management API consist of two parts: licenses management and products management. No caching is used with those endpoints.

Entities

The resources descriptions could be found on API documentation page Management Licenses v4 under schemas section.

LicenseResource

Typical license resource may look like the one below.

LicenseResource example

{
  "id": "42",
  "type": "License",
  "attributes": {
    "status": "ACTIVE",
    "start_date": 1523268666,
    "stop_date": 1523268698,
    "order_id": "1adc0dbe-3c65-4248-896c-78c049e276c8",
    "renew_record": {
      "recurring": true,
      "expiry_date": 1523268698
    },
    "purchase_record": {
      "price_currency_amount": 1223,
      "price_currency_iso4217": "EUR",
      "purchase_timestamp": 1526648593,
      "payment_method": "credit card"
    }
  },
  "relationships": {
    "user": {
      "data": {
        "id": "41",
        "type": "User"
      }
    },
    "product": {
      "data": {
        "id": "41",
        "type": "Product"
      }
    }
  }
}

ProductResource

Product resource may looks like one below.

ProductResource example

{
  "id": "41",
  "type": "Product",
  "attributes": {
    "title": "Sport channels meagpack",
    "description": "Complete collection fo all sports channels",
	"price_record": {
      "amount": 98,
      "currency": "EUR"
    },
	"license_defaults": {
		"duration": 518400,
		"auto_renew": false,
	},
	"is_premium": true,
    "auto_grant_on_signup": false,
    "is_user_visible": true,
    "is_buyable": 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"
        }
      ]
    }
  }
}

What is important to keep in mind here is the connection of product fields

"license_defaults": {
	"duration": 518400,
	"auto_renew": false,
}

with licenses crated for that product. Duration is value in seconds which will be used to set license expiry date, i.e. license associated with this product and given to user will have duration of time of creation plus this value. And the product auto_renew flag will be transferred to license recurring attribute.

Please note that it is recommended to clients to show as available for end-users to purchase only products with both is_user_visible and is_buyable attributes set. See Listing licenses and products for more information on topic.

Authorization

All BSS endpoints support API key authorization. The header named 'Authorization' with content "Apikey PUT_YOUR_KEY_HERE" must be passed with request.

In addition to API key authorization some clients can have IP white listing feature enabled, which will allow access only from exact IP's.

Both API key and IP addresses allowed list are customer specific data and you should contact support person to obtain those.

Licenses management

Fetch licenses

Endpoints overview

Id	Endpoint	HTTP method	Purpose
GetLicenses	/api/license/management/v4/licenses	GET	Fetch list of licenses with filters
GetLicenseById	/api/license/management/v4/licenses/{license_id}	GET	Get license specified by id
GetLicensesByUser	/api/license/management/v4/users/{user_id}/licenses	GET	Get all user licenses

BSS can get list of licenses with filters, all user licenses and single license.

GetLicenses and GetLicenseById calls return an array of licenses with all relationships and also contain included section with all products associated to fetched licenses. GetLicenses by default has a limit of 100 results per page and GetLicensesByUser will always return all results. Pleases check API documentation on GetLicenseById filtering parameters details.

GetLicenseById will return single license resource and associated product in included section.

Use cases

Get all licenses that are added to a user account

http://apidomain.xyz/api/license/management/v4/users/42/licenses

will return all licenses in one request with included products or

http://apidomain.xyz/api/license/management/v4/licenses?filter[user_id]=42

which will return paginated results with limit of 100 per page without included products but with included users

http://apidomain.xyz/api/license/management/v4/licenses?filter[user_id]=42&include=product

will return paginated results with limit of 100 per page with included products

Get licenses which were purchased by user during this last month

Users license API always specifies 'billing' as payment method. Please note that purchase_later_then value here is just example.

http://apidomain.xyz/api/license/management/v4/licenses?filter[user_id]=42&filter[payment_method]=billing&filter[purchase_later_than]=2017-07-21

Will return return paginated results with limit of 100 per page without included products and

http://apidomain.xyz/api/license/management/v4/licenses?filter[user_id]=42&filter[payment_method]=billing&filter[purchase_later_than]=2017-07-21&included=product

will return paginated results with limit of 100 per page with included products

Get second page of licenses that has no set payment method

http://apidomain.xyz/api/license/management/v4/licenses?filter[payment_method]=none&page[number]=2

BSS can get the products that are added to a user account

This operation can be done with same requests as above. Each response will have included section with products associated with granted licenses.

Create licenses

Endpoints overview

Id	Endpoint	HTTP method	Purpose
CreateLicense	/api/license/management/v4/licenses	POST	Grant license on specified product to user

The create license endpoint requires an Idempotency-Key parameter 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 allow retrying requests that might fail due to e.g. a network error without risking purchasing the same product twice. 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 there for safe to call the API multiple times if the response was lost, as long as the same idempotency key is used in subsequent requests.

If any of non-mandatory license parameters are omitted then the value will be taken from associated product.

Use cases

BSS can add product to a user account with a single call

Add product to a user

POST http://apidomain.xyz/api/license/management/v4/licenses
{
  "data": {
    "type": "License",
    "attributes": {
      "start_date": 1523268666,
      "stop_date": 1523268698,
      "renew_record": {
        "recurring": true
      },
      "purchase_record": {
        "price_currency_amount": 1223,
        "price_currency_iso4217": "EUR",
        "purchase_timestamp": 1526648593,
        "payment_method": "credit card"
      }
    },
    "relationships": {
      "user": {
        "data": {
          "id": "41",
          "type": "User"
        }
      },
      "product": {
        "data": {
          "id": "41",
          "type": "Product"
        }
      }
    }
  }
}
RESPONSE 201 Created
{
  "data": {
    "id": "42",
    "type": "License",
    "attributes": {
      "status": "ACTIVE",
      "start_date": 1523268666,
      "stop_date": 1523268698,
      "order_id": "1adc0dbe-3c65-4248-896c-78c049e276c8",
      "renew_record": {
        "recurring": true,
        "expiry_date": 1523268698
      },
      "purchase_record": {
        "price_currency_amount": 1223,
        "price_currency_iso4217": "EUR",
        "purchase_timestamp": 1526648593,
        "payment_method": "credit card"
      }
    },
    "relationships": {
      "user": {
        "data": {
          "id": "41",
          "type": "User"
        }
      },
      "product": {
        "data": {
          "id": "41",
          "type": "Product"
        }
      }
    }
  }
}

Delete licenses

Endpoints overview

Id	Endpoint	HTTP method	Purpose
DeleteLicenseById	/api/license/management/v4/licenses/{license_id}	DELETE	Delete license by id

Use cases

BSS can remove product from a user account with a single call

Remove product from a user

POST http://apidomain.xyz/api/license/management/v4/licenses/42
RESPONSE 204 Deleted

Batch operations

Endpoints overview

Id	Endpoint	HTTP method	Purpose
BatchCreateLicenses	/api/license/management/v4/licenses/batch_create	POST	Create multiple licenses
BatchDeleteLicenses	/api/license/management/v4/licenses/batch_delete	POST	Delete multiple licenses

Batch operations are limited to process up to 1000 items per request. Those endpoints are not designed to be high performant thus keep in mind that with big amount of input items it would take some time to receive a response. Also operation will fail on first occurred error and return error message for specified item.

BatchCreateLicenses request requires same Idempotency-Key parameter to be present in header same as described for CreateLicense endpoint. The response will contain included section with details on associated products.

Use cases

BSS can add multiple products to a user account with a single call

Add multiple products to multiple users

POST http://apidomain.xyz/api/license/management/v4/licenses/batch_create
{
  "data": [
    {
      "type": "License",
      "attributes": {
        "start_date": 1523268666,
        "stop_date": 1523268698,
        "renew_record": {
          "recurring": true
        },
        "purchase_record": {
          "price_currency_amount": 1223,
          "price_currency_iso4217": "EUR",
          "purchase_timestamp": 1526648593,
          "payment_method": "credit card"
        }
      },
      "relationships": {
        "user": {
          "data": {
            "id": "42",
            "type": "User"
          }
        },
        "product": {
          "data": {
            "id": "1",
            "type": "Product"
          }
        }
      }
    },
    {
      "type": "License",
      "attributes": {
        "start_date": 1523268999,
        "stop_date": 1523268876,
        "renew_record": {
          "recurring": true
        },
        "purchase_record": {
          "price_currency_amount": 342,
          "price_currency_iso4217": "EUR",
          "purchase_timestamp": 1523268999,
          "payment_method": "bank transfer"
        }
      },
      "relationships": {
        "user": {
          "data": {
            "id": "42",
            "type": "User"
          }
        },
        "product": {
          "data": {
            "id": "2",
            "type": "Product"
          }
        }
      }
    }
  ]
}

RESPONSE 201 Created
{
  "data": [
    {
      "id": "13",
      "type": "License",
      "attributes": {
        "status": "ACTIVE",
        "start_date": 1523268666,
        "stop_date": 1523268698,
        "order_id": "1adc0dbe-3c65-4248-896c-78c049e276c8",
        "renew_record": {
          "recurring": true,
          "expiry_date": 1523268698
        },
        "purchase_record": {
          "price_currency_amount": 1223,
          "price_currency_iso4217": "EUR",
          "purchase_timestamp": 1526648593,
          "payment_method": "credit card"
        }
      },
      "relationships": {
        "user": {
          "data": {
            "id": "42",
            "type": "User"
          }
        },
        "product": {
          "data": {
            "id": "1",
            "type": "Product"
          }
        }
      }
    },
	{
      "id": "13",
      "type": "License",
      "attributes": {
        "status": "ACTIVE",
        "start_date": 1523268999,
        "stop_date": 1523268876,
        "order_id": "1adc0dbe-3c65-4248-896c-78c049e276c8",
        "renew_record": {
          "recurring": true,
          "expiry_date": 1523268698
        },
        "purchase_record": {
          "price_currency_amount": 342,
          "price_currency_iso4217": "EUR",
          "purchase_timestamp": 1523268999,
          "payment_method": "bank transfer"
        }
      },
      "relationships": {
        "user": {
          "data": {
            "id": "42",
            "type": "User"
          }
        },
        "product": {
          "data": {
            "id": "2",
            "type": "Product"
          }
        }
      }
    }
  ],
  "included": [
    {
      "id": "1",
      "type": "Product",
      "attributes": {
        "title": "Sport channels meagpack",
        "description": "Complete collection fo all sports channels",
		"price_record": {
          "amount": 98,
          "currency": "EUR"
        },
		"license_defaults": {
			"duration": 518400,
			"auto_renew": false,
		},
		"is_premium": true,
        "auto_grant_on_signup": false,
		"is_user_visible": true,
        "is_buyable": 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"
            }
          ]
        }
      }
    },
	{
      "id": "2",
      "type": "Product",
      "attributes": {
        "title": "Discovery channels meagpack",
        "description": "Complete collection fo all Discovery channels",
        "is_premium": true,
        "price_record": {
          "amount": 98,
          "currency": "EUR"
        },
		"license_defaults": {
			"duration": 518400,
			"auto_renew": false,
		},
		"is_premium": true,
        "auto_grant_on_signup": false,
		"is_user_visible": true,
        "is_buyable": true
      },
      "relationships": {
        "live": {
          "data": [
            {
              "id": "1",
              "type": "Channel"
            }
          ]
        },
        "catchup": {
          "data": [
            {
              "id": "2",
              "type": "Channel"
            }
          ]
        },
        "npvr": {
          "data": [
            {
              "id": "3",
              "type": "Channel"
            }
          ]
        },
        "startover": {
          "data": [
            {
              "id": "4",
              "type": "Channel"
            }
          ]
        }
      }
    }
  ]
}

BSS can delete multiple products from a user account with a single call

Remove multiple products

POST http://apidomain.xyz/api/license/management/v4/licenses/batch_delete
{
  "data": [
    {
      "id": "2",
      "type": "License"
    },
	{
      "id": "7",
      "type": "License"
    },
	{
      "id": "34",
      "type": "License"
    }
  ]
}
RESPONSE 204 Deleted

BSS can revoke all subscribed products from a user

Client can perform same call as for removing multiple products from multiple users but limited to one user licenses.

Migration from legacy

POST `/api/management/user/<email>/product` endpoint is replaced with POST '/api/license/management/v4/licenses' endpoint and extended with POST '/api/license/management/v4/licenses/batch_create' endpoint for multiple entries.

DELETE '/api/management/user/<email>/product/<product_id>' endpoint is replaced with DELETE '/api/license/management/v4/licenses/{license_id}' endpoint and extended with POST '/api/license/management/v4/licenses/batch_delete' endpoint for multiple entries.

Products management

Fetch products

Id	Endpoint	HTTP method	Purpose
GetAllProducts	/api/license/management/v4/products	GET	Get all products
GetProductById	/api/license/management/v4/products/{product_id}	GET	Get product by Id

GetAllProducts returns a list of products with available services under relationships section. Default page size is 100 items and client can lust all products with page[number] parameter.

Use cases

BSS can get list of products

GET http://apidomain.xyz//api/license/management/v4/products

will return all products

BSS can get concrete product

GET http://apidomain.xyz//api/license/management/v4/product/42

Create products

Id	Endpoint	HTTP method	Purpose
CreateProduct	/api/license/management/v4/products	POST	Create new product

Use cases

BSS can create product and assign services to product

Let's create a product with live services for channels with ids [1, 2]

Create product

POST http://apidomain.xyz//api/license/management/v4/products
{
  "data": {
    "type": "Product",
    "attributes": {
      "title": "Sport channels meagpack",
      "description": "Complete collection fo all sports channels",
      "price_record": {
        "amount": 98,
        "currency": "EUR"
      },
      "license_defaults": {
        "duration": 518400,
        "auto_renew": false
      },
      "is_premium": true,
      "auto_grant_on_signup": false,
      "is_user_visible": true,
      "is_buyable": true
    },
    "relationships": {
      "live": {
        "data": [
          {
            "id": "1",
            "type": "Channel"
          },
		  {
            "id": "2",
            "type": "Channel"
          }
        ]
      }
    }
  }
}
RESPONSE 201 Created
{
  "data": {
	"id": 42
    "type": "Product",
    "attributes": {
      "title": "Sport channels meagpack",
      "description": "Complete collection fo all sports channels",
      "price_record": {
        "amount": 98,
        "currency": "EUR"
      },
      "license_defaults": {
        "duration": 518400,
        "auto_renew": false
      },
      "is_premium": true,
      "auto_grant_on_signup": false,
      "is_user_visible": true,
      "is_buyable": true
    },
    "relationships": {
      "live": {
        "data": [
          {
            "id": "1",
            "type": "Channel"
          },
		  {
            "id": "2",
            "type": "Channel"
          }
        ]
      }
    }
  }
}

Update products

Id	Endpoint	HTTP method	Purpose
UpdateProduct	/api/license/management/v4/products/{product_id}	PATCH	Update product attributes and relations

With this call only provided in request attributes/relations will be updated. The relationships could be updated only as a whole record. So keep in mind that if you want to add one more service to relationship you need to pass a list containing all already assigned services plus the one needed. The same refers to removal of services.

Use cases

BSS can update product and assign services to product

Let's use product created in previouse section. With the call below we are going to modify product title, set default product license duration to 10 years (which will lead to all licenses granted to this product will have 10 years expired date from issued date), add catchup service for channel 1, startover service for channel 2 and live service for new channel 3.

Update product and assign services

POST http://apidomain.xyz//api/license/management/v4/products/42
{
  "data": {
    "id": 42
    "type": "Product",
    "attributes": {
      "title": "Renamed Sport channels megapack",
      "license_defaults": {
        "duration": 315569520,
      },
    },
    "relationships": {
      "live": {
        "data": [
          {
            "id": "1",
            "type": "Channel"
          },
		  {
            "id": "2",
            "type": "Channel"
          },
          {
            "id": "3",
            "type": "Channel"
          }
        ]
      },
      "catchup": {
        "data": [
          {
            "id": "1",
            "type": "Channel"
          }
        ]
      },
      "startover": {
        "data": [
          {
            "id": "2",
            "type": "Channel"
          }
        ]
      }
    }
  }
}
RESPONSE 200 Updated
{
  "data": {
    "id": 42
    "type": "Product",
    "attributes": {
      "title": "Renamed Sport channels megapack",
      "description": "Complete collection fo all sports channels",
      "price_record": {
        "amount": 98,
        "currency": "EUR"
      },
      "license_defaults": {
        "duration": 315569520,
        "auto_renew": false
      },
      "is_premium": true,
      "auto_grant_on_signup": false,
      "is_user_visible": true,
      "is_buyable": true
    },
    "relationships": {
      "live": {
        "data": [
          {
            "id": "1",
            "type": "Channel"
          },
		  {
            "id": "2",
            "type": "Channel"
          },
          {
            "id": "3",
            "type": "Channel"
          }
        ]
      },
      "catchup": {
        "data": [
          {
            "id": "1",
            "type": "Channel"
          }
        ]
      },
      "startover": {
        "data": [
          {
            "id": "2",
            "type": "Channel"
          }
        ]
      }
    }
  }
}

BSS can update product and assign services to product

Using same product let's remove all services for channel 1.

Update product and remove services from product

POST http://apidomain.xyz//api/license/management/v4/products/42
{
  "data": {
    "id": 42
    "type": "Product",
    "attributes": {
      "title": "Renamed Sport channels megapack",
      "license_defaults": {
        "duration": 315569520,
      },
    },
    "relationships": {
      "live": {
        "data": [
		  {
            "id": "2",
            "type": "Channel"
          },
          {
            "id": "3",
            "type": "Channel"
          }
        ]
      },
      "catchup": {
        "data": [
        ]
      },
      "startover": {
        "data": [
          {
            "id": "2",
            "type": "Channel"
          }
        ]
      }
    }
  }
}
RESPONSE 200 Updated
{
  "data": {
    "id": 42
    "type": "Product",
    "attributes": {
      "title": "Renamed Sport channels megapack",
      "description": "Complete collection fo all sports channels",
      "price_record": {
        "amount": 98,
        "currency": "EUR"
      },
      "license_defaults": {
        "duration": 315569520,
        "auto_renew": false
      },
      "is_premium": true,
      "auto_grant_on_signup": false,
      "is_user_visible": true,
      "is_buyable": true
    },
    "relationships": {
      "live": {
        "data": [
		  {
            "id": "2",
            "type": "Channel"
          },
          {
            "id": "3",
            "type": "Channel"
          }
        ]
      },
      "startover": {
        "data": [
          {
            "id": "2",
            "type": "Channel"
          }
        ]
      }
    }
  }
}

Delete products

Id	Endpoint	HTTP method	Purpose
DeleteProductById	/api/license/management/v4/products/{product_id}	DELETE	Delete product by id

Use cases

BSS can remove product

Remove product created before

DELETE http://apidomain.xyz//api/license/management/v4/product/42
RESPONSE 204 No Content

Migration from legacy

GET `/api/user/<email>/product` endpoint is replaced with '/api/license/management/v4/products' endpoint

GET `https://boox.fi/api/user/<email>/product/<product_id>` endpoint is replaced with '/api/license/management/v4/products/{product_id}' endpoint.