Skip to main content

Monetization Service Technical Specification

Overview​

This document describes Monetization Service data model and technical interfaces. For a description of the Monetization Service user interface, see Monetization User Guide.

The Monetization Service provides a GraphQL API for management and publishing of subscription plans and claim sets. Billing Service, and other customizable services subscribe to published entities.

Each subscription plan can be associated with one or more payment providers like PayPal. For all payment providers, the same data model is applied, while there are provider-specific settings and restrictions.

Monetization Service container diagram

monetization-service-container

Data Model​

The Monetization Service stores data from different sources. This section describes all those sources and the related data.

The following diagram shows all entities stored by the Monetization Service. Different colors refer to the source of data. Blue entities are edited in and published by the Monetization Service.

Monetization Service data model

Constraints and Validation​

In general, blank, incomplete or invalid properties will not prevent an entity from being saved but they will prevent an entity from being published. A notable exception is that title properties must always be non-blank as the title is used to identify the entity in the UI.

Publish validation rules are described throughout the document in entity descriptions. Publish validation rules are also applied per payment provider. See payment provider specific documentation for details.

Locking of Published Data​

Most often products are defined on the payment provider side. Once such a product is defined there and activated, each payment provider has specific rules on what data can be changed. For instance, products and plans cannot be deleted in PayPal after they are activated. These rules are reflected in the Monetization Service by special constraints. This prevents the divergence of configuration between the Monetization Service and payment providers which might cause billing of existing subscriptions to fail.

Special constraints prevent the deletion of some published entities and prevent the editing of some published properties. Properties where these publication constraints apply are noted below.

Payment Provider​

Billing Service publishes details of enabled payment providers.

Each payment provider is defined by a key and a title. Each enabled payment provider can be assigned to subscription plans and then to payment plans that are children of those subscription plans.

Constraints

  • A payment provider cannot be disabled if it is in use by any published subscription plan
  • If a payment provider is changed from enabled to disabled then any associated configurations for this provider will be deleted

Subscription Plan​

A subscription plan defines an option for an end-user to subscribe to. Each subscription plan confers a set of benefits to each subscriber. These benefits are defined by associated claim sets. Each subscription plan may have multiple payment options defined by associated payment providers and payment plans.

Subscription plans are publishable entities. When publishing a subscription plan all child entities are also published, forming a single document. See Subscription Plan Publication for more details.

A single cover image can be associated with each subscription plan. Images must first be uploaded to Image Service with type "Subscription Plan Cover Image"

If a subscription plan is deleted all child payment plans and provider configs are also deleted.

Subscription plan properties

PropertyTypeDescriptionExample
titleStringDisplay name for the subscription plan. This will be shown to potential subscribers.Premium
descriptionStringA description for the subscription plan. This should describe the benefits to a potential subscriber.Watch all movies and all TV shows from our catalog
is_activeBooleanDetermines whether this subscription plan can be used by new subscribers. Existing subscriptions to an inactive subscription plan will continue to be billed. NOTE: like any other published property, the subscription plan must be published for changes to take effect.true
publication_stateEnumNOT_PUBLISHED: Never published, PUBLISHED: Published in its current state, CHANGED: Changed since last publication (or a child entity was changed / added / removed, or an association to an entity was added / removed).PUBLISHED
published_dateDate (1)The date when last published.2022-02-24T14:17:35+00:00

(1) ISO 8601 date and time including time zone

Publish validation

  • At least one child subscription plan provider config is required
  • At least one child payment plan is required

Publish constraints

  • Published subscription plans cannot be deleted

Subscription Plan Provider Config​

A subscription plan providers config associates a payment provider with a subscription plan. A subscription plan can have one provider config for each enabled payment provider.

Subscription plan provider config properties

PropertyTypeDescriptionExample
external_idStringReferences a product or other entity configured in the payment provider’s system. See payment provider specific documentation for more details.For PayPal this might look like: PROD‑9E661234S2214858A
publication_stateEnumNOT_PUBLISHED: Never published, PUBLISHED: Published in its current state, CHANGED: Changed since last publication.PUBLISHED
published_dateDate (1)The date when last published.2022-02-24T14:17:35+00:00

(1) ISO 8601 date and time including time zone

Publish validation

  • Property validation depends on the payment provider (see payment provider specific documentation). For some payment providers external_id must be blank
  • The subscription plan must have at least one child payment plan with a provider config for the same payment provider. i.e. if payment provider PAYPAL is associated to the subscription plan, it must also be associated to on at least one payment plan

Publish constraints

  • Published subscription plan provider configs cannot be deleted
  • external_id may not be changed after publication

Payment Plan​

A payment plan defines a payment option for an end-user to subscribe to a subscription plan. Each payment plan has a defined recurring period. Each payment plan may support multiple payment providers, and a price and currency per supported country.

Payment plans are child entities of subscription plans. When a subscription plan is published, details of all child payment plans are included and the publication state of all child payment plans will be changed to PUBLISHED.

If a payment plan is deleted all child prices and provider configs are also deleted.

Payment plan properties

PropertyTypeDescriptionExample
titleStringDisplay name for the payment plan. This will be shown to potential subscribers.Premium Monthly
descriptionStringA description for the payment plan. This should describe payment terms and the benefits to a potential subscriber.Pay monthly to watch all movies and all TV shows from our catalog
is_activeBooleanDetermines whether this payment plan can be used by new subscribers. Existing subscriptions to an inactive payment plan will continue to be billed. NOTE: if the parent subscription plan is not active then this property is ignored.true
period_quantityIntegerDefines the period for recurring subscription payments. Some payment providers may only support a subset of the available options. See payment provider specific documentation for details.4
period_unitEnumUnit of the period_quantity: DAY / WEEK / MONTH / YEAR.WEEK
publication_stateEnumNOT_PUBLISHED: Never published, PUBLISHED: Published in its current state, CHANGED: Changed since last publication (or a child entity was changed / added / removed).PUBLISHED
published_dateDate (1)The date when last published.2022-02-24T14:17:35+00:00

(1) ISO 8601 date and time including time zone

Publish validation

  • At least one child payment plan provider config is required
  • At least one child payment plan price is required
  • period_quantity must be a positive integer
  • period_unit must be set

Publish constraints

  • Published payment plans cannot be deleted
  • period_quantity may not be changed after publication
  • period_unit may not be changed after publication

Payment Plan Provider Config​

A payment plan providers config associates a payment provider with a payment plan. A payment plan can have up to one provider config for each payment provider. Only payment providers associated with the parent subscription plan can be selected.

Payment Plan Provider Config properties

PropertyTypeDescriptionExample
external_idStringReferences a product or other entity configured in the payment provider’s system. See payment provider specific documentation for more details.For PayPal this might look like:P‑7WJ927493M782507BMIJIBGY
publication_stateEnumNOT_PUBLISHED: Never published, PUBLISHED: Published in its current state.PUBLISHED
published_dateDate (1)The date when last published.2022-02-24T14:17:35+00:00

(1) ISO 8601 date and time including time zone

Publish validation

  • Property validation depends on the payment provider (see payment provider specific documentation)

Publish constraints

  • Published payment plan provider configs cannot be deleted
  • external_id may not be changed after publication

Payment Plan Price​

A payment plan price defines a price and currency for a payment plan in a single country. Subscribers will not be able to subscribe from a country that is not listed. Each payment plan may support multiple countries, but each country can only have a single price and currency.

Payment Plan Price properties

PropertyTypeDescriptionExample
countryString (1)The country where this price can be used.DE
currencyString (2)The currency to be used in this country.EUR
priceDecimalThe recurring price in the selected currency. Up to 5 decimal places are supported.9.99
publication_stateEnumNOT_PUBLISHED: Never published, PUBLISHED: Published in its current state, `CHANGED``: Changed since last publication.PUBLISHED
published_dateDate (3)The date when last published.2022-02-24T14:17:35+00:00

(1) ISO 3166-1 alpha-2 country format e.g. “DE”, “US”, “CN”…
(2) ISO 4217 currency e.g. “EUR”, “CNY“ or “USD”
(3) ISO 8601 date and time including time zone

Publish validation

  • Each payment provider may have specific validation rules (see payment provider specific documentation)

Publish constraints

  • country cannot be changed for published payment plan prices. This means that a country cannot be removed, although the price and currency for that country can be changed.

Claim Definitions Schema​

A claim defines a specific permission or restriction that should be applied when evaluating if an end-user is entitled to have access to some content (e.g. a movie). The claim definitions schema defines the full set of available claims. To understand how claims are associated with subscription plans see Claim Sets.

The claim definitions schema is stored in Monetization Service as claim definition and claim definition group entities. Each claim definition must belong to a single claim definition group. Claim definition groups are used mainly for UI categorization but they can also define selection rules. If a claim definition group has selection_mode=SINGLE then only a single claim from this group can be selected for any claim set.

The claim definitions schema is synchronized to the Monetization Service by sending a command via the Mosaic message bus. See Synchronize Claim Definitions Schema for details of this interface. After enabling the Monetization Service for a new environment, a simple claim definitions schema will be created for demonstration purposes. When a new claims definition schema is synchronized, the demo claims will be removed.

Claim definition properties

PropertyTypeDescriptionExample
claimStringA unique key used to identify this claim. The value must be unique and cannot be repeated in multiple groups.QUALITY_UHD2
titleStringDisplay name for the claim.UHD2 Quality (8K)
order_positionIntegerThe order that claim definitions within a group are defined.1

Claim definition group properties

PropertyTypeDescriptionExample
titleStringA unique display name for the group.Maximum Quality
selection_modeEnum (SINGLE / MULTIPLE)Whether multiple claims from the same group can be selected for a claim set.SINGLE
order_positionIntegerThe order that claim definition groups are defined.1

Claim Set​

A claim set defines a specific selection of claims (permissions and restrictions) that confer benefits to an subscriber. The list of selected claims is defined by associations to one or more claim definitions. Each subscription plan can have one or multiple associated claim sets.

The grouping of claims into claim sets, and the association of claim sets to subscription plans allows for a lot of flexibility in how benefits can be assigned to subscription plans. For example some claim sets may give access to certain sets of content, while other claim sets control the maximum streaming quality or the number of devices that can be streaming in parallel. These claim sets can be combined to any number of subscription plans, and the claim sets and subscription plans can be edited and published on different schedules.

Claim sets are publishable entities. The published claim set includes the list of associated claims. Unlike subscription plans, claim sets can be unpublished. See Claim Set Publication for more details.

Claim set properties

PropertyTypeDescriptionExample
titleStringDisplay name for the claim set.Premium streaming
descriptionStringA description for the claim set.Streaming benefits for premium subscriptions
keyStringA unique key used to identify this claim set in external systems. 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.CAN_STREAM_MAXIMUM_QUALITY
claimsString[]The list of claims associated with this claim set.[ 'QUALITY_UHD2' ]
publication_stateEnumNOT_PUBLISHED: Never published, PUBLISHED: Published in its current state, CHANGED: Changed since last publication (or an association to an entity was added / removed).PUBLISHED
published_dateDate (1)The date when last published.2022-02-24T14:17:35+00:00

(1) ISO 8601 date and time including time zone

Publish validation

  • Claim set key must not be blank
  • Must be associated with at least one claim definition (one claim must be selected)
  • Claims must be selected according to grouping rules. Only a single claim can be selected from each claim definition group with selection_mode=SINGLE

Publish constraints

  • Published claim sets cannot be deleted
  • Published claim sets cannot be unpublished if associated with a published subscription plan
warning

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.

Interfaces​

The Monetization Service provides programmatic interfaces for different scenarios.

Monetization API​

The Monetization API is a GraphQL API exposed to management applications. It expects a JWT token from the Identity Service. In general, direct integration with the Monetization API is not required as all operations are supported through the workflows available in the Mosaic management portal.

You can find the GraphiQL IDE for the EU region with the GraphQL schema under this URL: https://monetization.service.eu.axinom.net/graphiql

The API provides an interface to the full entity graph stored by the Monetization Service. This includes all the entities that are described in the Data Model section with all the relations between the entities to query, filter, and sort. All management data can be modified through the API according to the constraints defined the the Data Model section.

Messaging​

The Monetization Service integrates with the Mosaic RabbitMQ message bus. The Monetization Service publishes events and implements various message handlers to process events and commands from other systems. Relevant details and message schemas for integration with customizable services are defined in the Integration section.

Integration​

Synchronize Claim Definitions Schema​

The Claim Definitions Schema should be defined by an external service (usually Entitlement Service) and synchronized to the Monetization Service. It is expected that the claim definitions schema is defined statically in code, but it is also possible to be generated dynamically. An example might be to build claims based on published catalog metadata such as genres. e.g: MOVIES_WITH_GENRE_ACTION, EPISODES_WITH_GENRE_SITCOM. The claim definitions schema must be synchronized with the Monetization Service whenever it changes.

The Monetization Service accepts a synchronize-claim-definitions-start-command message via the Mosaic message bus.

Message schemaDescription
synchronize-claim-definitions-start-command (1)Update the claim definitions schema. The entire schema must be defined in the payload. Any omitted claim definitions will be deleted.

(1) Message schemas are defined using the JSON Schema specification. Messages schemas are defined in @axinom/mosaic-messages

Example 'synchronize-claim-definitions-start-command' payload
{
    "claim_definition_groups": [{
            "title": "Entity types",
            "selection_mode": "MULTIPLE",
            "claim_definitions": [{
                    "claim": "ENTITY_TYPE_EPISODES",
                    "title": "All movies"
                },
                {
                    "claim": "ENTITY_TYPES_EPISODES",
                    "title": "All episodes"
                }
            ]
        },
        {
            "title": "Maximum Quality",
            "selection_mode": "SINGLE",
            "claim_definitions": [{
                    "claim": "QUALITY_UHD2",
                    "title": "UHD2 Quality (8K)"
                },
                {
                    "claim": "QUALITY_UHD1",
                    "title": "UHD1 Quality (4K)"
                },
                {
                    "claim": "QUALITY_HD",
                    "title": "HD Quality (1080p)"
                },
                {
                    "claim": "QUALITY_SD",
                    "title": "SD Quality (< 720p)"
                }
            ]
        }
    ]
}

Upon receiving a synchronize-claim-definitions-start-command, the payload is validated against the defined schema and rules defined in the Data Model section. If validation is successful operations are performed to update the claims definition schema in the Monetization Service database. Updating the claim definitions schema is not generally a destructive process, but there are some operations which can affect existing claim sets:

Operations which will not affect claim sets:

  • Changing claim definition titles
  • Changing claim definition group titles
  • Adding a new claim definition group
  • Adding claim definitions to a group

Operations which will not change claim sets but may cause them to become invalid for publication. e.g. by changing group selection_mode to SINGLE where multiple claims are selected by one claim set. In this case the claim set must be edited before publication:

  • Changing claim definition group selection mode
  • Moving claim definitions between groups

**Operations which may change existing claim sets. If a selected claim no longer exists, and there is no new claim with a matching claim property then it will be removed from the claim set and the publication status will become 'CHANGED'. **

  • Deleting claim definitions
  • Changing the claim property of claim definitions

Synchronize Claims Definitions Schema Result Messages​

A result message is published by Monetization Service when processing of a synchronize-claim-definitions-start-command message finishes. The sender of the original message can subscribe to these events to take appropriate action. In case of a failure it might be useful to inform some developer/admin, or at least to log the issue as an error.

Message schemaDescription
synchronize-claim-definitions-finished-event (1)Published on successfully updating the claim definitions schema.
synchronize-claim-definitions-failed-event (1)Published if validation of the original message fails or if updating the claim definitions schema results in an error.

(1) Message schemas are defined using the JSON Schema specification. Messages schemas are defined in @axinom/mosaic-messages

Subscription Plan Publication​

Subscription plan publication is implemented by 2 GraphQL endpoints:

  1. Validation query: validateSubscriptionPlan
  2. Publish mutation: publishSubscriptionPlan

If there are no validation errors, a payloadHash property is included in the validation query response. This payloadHash must be included as a parameter to the subsequent publish mutation to ensure that the validated data has not been changed between the validation and publishing steps.

Sequence diagram for subscription plan publishing

Event schema​

A subscription plan published event is published when a new or existing subscription plan is published. The subscription plan payload includes all payment plans, pricing and provider settings.

Message schemaDescription
subscription-plan-published-event (1)Subscription plan properties including child payment plans, provider configs, prices and references to assigned claim sets

(1) Message schemas are defined using the JSON Schema specification. Messages schemas are defined in @axinom/mosaic-messages

Example 'subscription-plan-published-event' payload
{
    "id": "21029e04-2462-4e38-af6e-a395274f7418",
    "title": "Premium",
    "is_active": true,
    "description": "Watch all movies and all TV shows from our catalog.",
    "provider_configs": [{
        "payment_provider_key": "PAYPAL",
        "external_id": "PROD-premium"
    }],
    "payment_plans": [{
        "id": "80190b19-d7e2-4d2c-ad73-4175aba7f509",
        "title": "Monthly",
        "description": "Pay monthly to watch all movies and all TV shows from our catalog.",
        "is_active": true,
        "period_unit": "MONTH",
        "period_quantity": 1,
        "provider_configs": [{
            "payment_provider_key": "PAYPAL",
            "external_id": "P-DHOAS7DJIC96DSAUHDISHAU65"
        }],
        "prices": [{
            "country": "EE",
            "currency": "EUR",
            "price": 9.99
        }, {
            "country": "DE",
            "currency": "EUR",
            "price": 9.99
        }]
    }],
    "claim_set_keys": ["CAN_VIEW_PREMIUM_CONTENT","CAN_STREAM_MAXIMUM_QUALITY"],
    "images": [{
        "width": 1300,
        "height": 1600,
        "type": "COVER",
        "path": "/transform/0-0/LWdMpMnGHnh98aJ5vGE14G.jpg"
    }]
}

Claim Set Publication​

Claim Set publication is implemented by 2 GraphQL endpoints. The endpoints and process are similar to subscription plan publication.

  1. Validation query: validateClaimSet
  2. Publish mutation: publishClaimSet

If there are no validation errors, a payloadHash property is included in the validation query response. This payloadHash must be included as a parameter to the publish mutation to ensure that the validated data has not been changed between the validation and publishing steps.

The sequence for claim set publishing is the same as for subscription plan publishing, except that there is no integration with image service.

Event schema​

A claim set published event is published when a new or existing claim set is published.

Message schemaDescription
claim-set-published-event (1)Claim set including the list of associated claims

(1) Message schemas are defined using the JSON Schema specification. Messages schemas are defined in @axinom/mosaic-messages

Example 'claim-set-published-event' payload
{
    "key": "CAN_STREAM_MAXIMUM_QUALITY",
    "title": "Can stream at 8K quality",
    "description": "Can stream content at any supported quality.",
    "claims": ["QUALITY_UHD2"]
}

Claim Set Unpublish​

A claim set unpublished event is sent when a claim set is unpublished. Subscribing systems can consider the claim set as deleted, but they should also consider that the claim set may be republished in future, or another claim set may be published with the same key.

Message schemaDescription
claim-set-unpublished-event (1)Claim set key to be unpublished

(1) Message schemas are defined using the JSON Schema specification. Messages schemas are defined in @axinom/mosaic-messages

Example 'claim-set-unpublished-event' payload
{
    "key": "CAN_STREAM_MAXIMUM_QUALITY"
}