Creating a product

Request

To create a product, send a POST request to:

CODE

https://<host>:<port>/metadata/commercial/v1/products

This request only creates a product – it does not associate any content to it.

To associate content to the product, you must create productLinks. See Creating product links.

Headers

Content-Type: application/json

Mandatory arguments

All of the following arguments are part of the request body:

Either:
- id – the ID of the product, or
- Both providerId and providerResourceId
name – the product name
technicalTypes – the supported playable asset types (technical types) as a semicolon-separated list
start – the product's validity start date (in ISO 8601 format)
end – the product's validity end date (in ISO 8601 format)
type – the product's type. Must be one of:
- transactional
- subscription
- capability

Other arguments

The following arguments (all in the request body) are all optional.

However, they may be required by ION (if you are using it). These are indicated with an asterisk (*).

isFreemium – whether the product is a freemium product (true or false). If this is set to true, the freemium element must be included.
freemium – defines the date range when freemium can be activated and the free period duration once it has been activated. Contains:
- start – the start date of the freemium availability period in ISO 8601 format
- end – the end date of the freemium availability period in ISO 8601 format
- validityPeriod – the duration of the free period per account. The format is ISO 8601 with a restricted pattern that must be one (and no more) of PnY, PnM, PnW, or PnD.
published – a flag (true or false) that allows you to indicate whether the product should be published (displayed) to the end user or not.
isShared – for transactional products only, whether this is a shared product. (A shared product allows you to set the price (and other terms) for all the individually purchasable VOD content items that belong to the product in a single place, that is, on the product. This saves having to define a product for each content and set the price separately on each one.) See Transactional VOD (TVOD).
If you want to price a content item individually, set isShared to false and only add the single content item to the product (and no others).
If you want to assign the same price to multiple content items, set isShared to true and add all the relevant content items to this product.
nominalPrice – the price of the product and the currency in which the price is expressed:
- amount* – the price
- currency* – the currency. This can be any string, but use of the ISO 4217 format is recommended.
purchasablePeriod – the period during which the product can be purchased. If not specified, there are no time limits for the purchase period. It contains:
- start* – the purchasing period start date in ISO 8601 format
- end* – the purchasing period end date in ISO 8601 format
rights – content consumption properties:
- impulsive – whether the product can be purchased directly through a client application (true) or only via the operator (false). Default: false.
- rentalDuration – the rental duration. The format is ISO 8601 with a restricted pattern of PnDTnHnMnS.
- consumptionWindow – the time period after purchase during which initial content consumption can happen. If this is set, it means that relative licensing is being used (and not absolute licensing). Once the user starts watching, they can continue watching or watch the content again at any time during the rental duration period. The format is ISO 8601 with a restricted pattern of PnDTnHnMnS.
- storageAllowed – whether download is permitted for the content that belongs to the product (true or false). For live subscriptions, this includes content captured from a channel and made available through catch-up or recording.
  Note that OpenTV Video Platform does not yet provide authorisation services for downloaded content. This flag indicates that clients can download content, as long as authorisation is handled by a third-party system.
- storageDuration – for downloaded content, the length of time that the content can be stored before expiring (in ISO 8601 format). Only relevant if storageAllowed is true.
- storageStartPeriod – for downloaded content, the time within which the first download of an asset may occur (in ISO 8601 format). Only relevant if storageAllowed is true.
billingModel – for subscription products, the billing model (that is, the billing period). Contains:
- period* – the billing period. The value is in ISO 8601 format with the pattern restricted to one of PnY, PnM, PnW, or PnD.
capabilityProductInfo – type and access period for capability type products:
- type – the capability type
- accessDuration – the amount of time for which the capability is available to the user after purchase. The value is in ISO 8601 format with the pattern restricted to one of PnY, PnM, PnW, or PnD.
metadataSet* – a set of locale-specific metadata blocks, each of which has:
- locale* – the locale for the metadata element. If locale is set to none, the metadata block that it applies to is the default – it is the one that is used if there is no metadata block for the user's locale.
- metadata* – a block containing one or more key/value pairs in the following form:
  JSON
```
[{
   "key": "<key_name>",
   "value": "<value>"
}]
```
  You can add whatever keys you require. However, the following values have significance in OpenTV Platform:
  - TitleForProduct* – the product's title
  - Rating – the product's rating
  - CMS4ProductType – specifies whether this is a CMS4ProductType or not.

An individual content item can be made available for purchase:

On its own, priced individually for purchase or renting
As part of a collection, where the price is set on the collection as a whole. When a customer purchases the collection, they get access to all of the items in the collection.
As part of a shared product, where the price is set only on the shared product. Each item that belongs to the shared product is available for purchase on its own, at the price that is set on the shared product.

An individual content item may be:

Priced and sold individually and also available as part of a collection.
Priced as part of a shared product and also available as part of a collection.

However, it may not be both priced and sold individually and priced as part of of a shared product.

Note that you are responsible for ensuring that items are not priced both individually and as part of a shared product. OpenTV Video Platform does not validate or enforce this.

Example

A POST request with this payload creates a new product:

CODE

{
    "id": "DefaultNFXSUBProduct",
    "providerId": "OPERATOR",
    "providerResourceId": "DefaultNFXSUBProduct",
    "technicalTypes": "SD;HD;DASH;HLS",
    "name": "DefaultNFXSUBProduct",
    "start": "2018-12-31T13:00:00Z",
    "end": "2021-10-02T06:13:35Z",
    "metadataSet": [{
        "locale": "en_AU",
        "metadata": [{
            "key": "TitleForProduct",
            "value": "DefaultNFXSUBProduct"
        }]
    }],
    "type": "subscription",
    "nominalPrice": {
        "amount": 0,
        "currency": "AUD"
    }
}

Response

A successful request returns an HTTP 201 status. The response body contains the URI of the newly-created product.

A bad request returns an HTTP 400 status.