Monetization Service
Management service to create business models like AVOD, SVOD, TVOD. Configuration of products, pricing and currencies, and integration of external payment providers, e.g. PayPal, Google Play.
Overview
Monetization Service is a managed multi-tenant service that maintains the data about available Subscription Plans and Payment Plans. It provides a GUI for management and publishing of the data consumed by other services.
Monetization Service is a part of a larger Monetization and Billing context.
Monetization Service container diagram
Data Model
The Data Model is described in context of the Monetization and Billing context.
Monetization Service stores data in a relational database. Monetization Service owns the following entities and stores them in its database:
- Subscription Plans
- Payment Plans
- Claim Sets
- Bundles.
It also stores:
- A snapshot of a Claims Definition Schema, received from the Entitlement Service
- A snapshot (names only) of the Payment Providers, received from the Billing Service
Locking of Published Data
Due to specific requirements of payment provider integration, some special constraints are applied to published entities which prevent the editing and removal of published entities and/or properties. These constraints are applied to prevent configurations from diverging from those in use by configured payment providers which might cause billing of existing subscriptions to fail.
Properties where these publication constraints apply are noted below.
Interfaces
Monetization Service API provides a GraphQL API for management and publishing of all entities. Monetization API also implements command handlers for processing of messages from other services.
Workflows
Monetization Service provides management and publishing workflows for its all entities. The workflows are available from the Management System once the service is activated for a specific environment.
As well as the Monetization API, Monetization workflows also use:
- Image Service - for thumbnails attached to Subscription Plans
- Media Service - to select entities for the Bundles
The monetization hub page is an entry point to Monetization Management Stations.
Monetization Hub
Subscription Plans
The Subscription Plans explorer lists all Subscription Plans. The Publication State of each Subscription Plan is indicated by a color on the left.
A new Subscription Plan can be created with the "NEW" button on the right of the title bar. Upon creating a new Subscription Plan, or opening a Subscription Plan from the explorer page, the Subscription Plan Details page will be displayed.
Subscription Plan Details station
Properties edited at the Subscription Plan Details station will be saved on navigating away from the page, but will have no effect until the Subscription Plan is published.
Subscription Plan editable properties
| Property | Description |
|---|---|
| Title | Display name for Subscription Plan. The title will be used to identify the Subscription Plan in the Monetization Service UI and will be published for display in other systems including to potential subscribers. |
| Description | A description for the Subscription Plan. This should describe the benefits to a potential subscriber. |
| Status | Determines whether new subscriptions can be made with this Subscription Plan. Existing subscriptions to an inactive Subscription Plan will continue to be billed. NOTE: as with other properties the Subscription Plan must be published for changes to take effect. |
| Payment Providers and Settings | Add / remove the list of Payment Providers that can be used to subscribe. At least one Payment Provider must be enabled. For each enabled payment provider, at least one Payment Plan must enable the same payment provider. The UI and publish validation for settings varies per supported payment provider. See payment provider specific documentation for details. |
Subscription Plan actions
- Claim Sets Management - Add / remove assigned to Claim Sets.
- Payment Plans - Opens the Payment Plans explorer station to manage Payment Plans owned by this Subscription Plan.
- Manage Cover Image - Assign a Subscription Plan Cover Image that is uploaded to Image Service.
- Publishing - Validate and publish the Subscription Plan. See Publishing.
- Delete - Delete the Subscription Plan including owned Payment Plans.
Published Subscription Plans cannot be deleted.
Payment Plans
The Payment Plans explorer station lists the Payment Plans owned by a Subscription Plan. The Publication State of each Payment Plan is indicated by a color on the left. Note that Payment Plans are always published with the parent Subscription Plan.
A new Payment Plan can be created with the "NEW" button on the right of the title bar. Upon creating a new Payment Plan, or opening a Payment Plan from the explorer page, the Payment Plan Details page will be displayed.
Payment Plan Details station
Properties edited at the Payment Plan Details station will be saved on navigating away from the page, but will have no effect until the parent Subscription Plan is published.
Payment Plan editable properties
| Property | Description |
|---|---|
| Title | Display name for Payment Plan. The title will be used to identify the Payment Plan in the Monetization Service UI and will be published for display in other systems including to potential subscribers. |
| Description | A description for the Payment Plan. This should describe payment terms and the benefits to a potential subscriber. |
| Status | Determines whether new subscriptions can be made with this Payment Plan. Existing subscriptions to an inactive Payment Plan will continue to be billed. If the parent Subscription Plan is inactive then this property is ignored. |
| Recurrence Period | Required. Defines the recurring Subscription Period. Some payment provider may only support a subset of the available options. This will be validated before publishing. See payment provider specific documentation for details. NOTE: The recurrence period cannot be changed after publication. |
| Payment Providers and Settings | Add / remove the list of Payment Providers that can be used to subscribe. Only Payment Providers which are enabled on the parent Subscription Plan can be used. At least one Payment Provider must be enabled. The UI and publish validation for settings varies per supported payment provider. See payment provider specific documentation for details. |
Subscription Plan actions
- Price per Country - Manage price and currency per country.
- Delete - Delete the Payment Plan.
Published Payment Plans cannot be deleted.
Price per Country
The Price per Country explorer station lists prices configured for a single Payment Plan.
Price per Country station
A single price and currency can be configured for each country where this Payment Plan can be used. Subscribers will not be able to subscribe from a country that is not listed. At least one country must be added per Payment Plan. This will be validated before Subscription Plan publishing.
Prices will be saved on navigating away from the page, but will have no effect until the parent Subscription Plan is published.
Published countries cannot be removed, but the currency and price for published countries can be changed. Although publication state per country is not directly displayed in the UI, the delete (X) button is disabled for published countries.
Claim Sets
The Claim Sets explorer lists all Claim Sets. The Publication State of each Claim Set is indicated by a color on the left.
A new Claim Set can be created with the "NEW" button on the right of the title bar. Upon creating a new Claim Set, or opening a Claim Set from the explorer page, the Claim Set Details page will be displayed.
Claim Set Details station
Properties edited at the Claim Set Details station will be saved on navigating away from the page, but will have no effect until the Claim Set is published.
Claim Set editable properties
| Property | Description |
|---|---|
| Title | Display name for Claim Sets. The title will be used to identify the Claim Set in the Monetization Service UI and will be published for display in other systems. |
| Description | A description for the Claim Set. |
| Unique Key | A unique key used to assign the claim set to Subscription Plans. As an identifier published with the Subscription Plan, the unique key will be known by the frontend and can be used to customize the user experience. NOTE: The unique key cannot be changed when the Claim Set is published. |
Claim Set actions
- Claims - Manage the claims assigned to the Claim Set.
- Publishing - Validate and publish the Claim Set. See Publishing.
- Unpublish - Unpublish the Claim Set.
- Delete - Delete the Subscription Plan including owned Payment Plans.
Published Claim Sets cannot be deleted. Claim Sets can be unpublished, but not while assigned to a published Subscription Plan.
After unassigning a Claim Set from a Subscription Plan ensure the change to the Subscription Plan is published before the Claim Set is unpublished. Failure to do so may cause Claims to not work as expected.
Claims
The Claims editor is used to select the Claims assigned to a Claim Set. At least one claim must be selected to publish the Claim Set.
Claim Set Details station
The full list of selectable Claims is divided into groups with each group represented by a horizontal section. The visibility of each section can be toggled. Each section includes a context menu with an option to 'Deselect all' from that group.
There are several distinct user interfaces for claims groups. Each is used for groups with specific properties:
A claims group with selection mode SINGLE is displayed as a list of radio buttons. At most one claim from the group can be selected.
A claims group with selection mode MULTIPLE and 5 or less claim options is displayed as a list of checkboxes. Any number of claims from the group can be selected.
A claims group with selection mode MULTIPLE and more than 5 claim options is displayed as a dynamic list to which items can be added through a modal explorer. Open the modal explorer with the '+' button. The modal explorer lists all remaining claims from the group with abilities to filter and bulk select items.
Publishing
Subscription Plans and Claim Sets share a common publication process. Publication is a 2-step process:
- Validate
- Publish
Upon pressing "Publishing", validation rules are applied, and a list of errors and warnings are displayed. The validation page is always displayed even in the case that there no issues so it is safe to click "Publishing" to see the current validation state even if you do not wish to publish at the time.
- Errors prevent publication.
- Warnings do not prevent publication.
Subscription Plan Publishing errors
Each error or warning message will clearly state where the issue is. Resolve any errors, and click "Publishing" again to re-run validation.
If validation succeeds without any errors, then a "Publish" button is displayed.
Subscription Plan Publishing validation
Click the "Publish" button and confirm to publish. An additional check will run to ensure that changes have not been made since validation.
Successful publishing has the following effects:
- A publication event will be published to a message bus which will be received by relevant services.
- The Publication state of published entities with change to
PUBLISHED.
Publication State
Publication state is a common property shared by all publishable entities.
Publication state key
| Explorer Color | Value | Description |
|---|---|---|
| Gray {set:cellbgcolor:#DDDDDD} | NOT_PUBLISHED {set:cellbgcolor:none} | This entity has never been published. |
| Green {set:cellbgcolor:#FFC81A} | PUBLISHED {set:cellbgcolor:none} | This entity is published. No changes have been made since last publication. |
| Orange {set:cellbgcolor:#95C842} | CHANGED {set:cellbgcolor:none} | This entity is published. Changes have been made since last publication. This includes changes to a child entity or relation which result in a change to the published message payload. E.g. if a new Payment Plan is added to a PUBLISHED Subscription Plan, the new payment plan will be NOT_PUBLISHED and the parent subscription plan will be CHANGED. |
Authentication & Authorization
Monetization Service is a managed service. All API communication requires a JWT bearer token issued by the Identity Service.
Permissions
The following permissions are defined by Monetization Service.
| Permission | Description |
|---|---|
| Admin | Full access |
| Subscription plans: View | View Subcription Plan properties and all child entities (Payment Plans, Provider Configs, Prices) |
| Subscription plans: Manage | View, edit and publish Subcription Plans and all child entities (Payment Plans, Provider Configs, Prices) |
| Claim sets: View | View Claim Sets and assigned claims |
| Claim sets: Manage | View, edit and publish Claim Sets and assigned claims |
| Claim Definitions: Synchronize | Update claim definitions. This permissions is intended for service accounts only. |
Administration
The following items can be configured for the Monetization Service in the Mosaic Admin Portal:
- Payment Providers and their configuration
Billing
The service fee follows the tiered model depending on the number of maintained Subscription Plans. See Mosaic Pricing for more details.