Skip to content
Vimond Vimond Vimond Developer Hub

SVOD: Subscription-based Video on Demand

In this guide, we’ll go through some of the different ways for end-users to view and manage their active subscriptions. Additionally, we’ll learn how to stop or reactivate these subscriptions as per the viewer’s preferences.

Let’s dive into the details and empower your viewers with a seamless subscription experience!

SVOD and VIA Monetise

Section titled “SVOD and VIA Monetise”

SVOD’s payment flow mirrors Transactional-based Video on Demand (TVOD), however, SVOD empowers users with unlimited access to a library of content through subscription-based models rather than renting or purchasing access to individual assets.

VIA Monetise subscription APIs

Section titled “VIA Monetise subscription APIs”

Get active subscriptions

Section titled “Get active subscriptions”

Once a viewer purchases access through the payment gateway, you may want to allow them to view their active subscriptions, and stop or reactivate them. The first step of this would be to display all the active subscriptions for the viewer. To do this we retrieve all active subscriptions with the curl below.

❗️ Note

If a given viewer does not have any valid subscriptions, this endpoint will return 200 OK and an empty list whether you have a valid Bearer token or not.

GET /api/:platform/user/:userId/orders/current
curl -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer (token)" \
  "https://api.yoursite.com/api/:platform/user/:userId/orders/current"
[
  {
    "order": {
      "@uri": "/api/web/order/19003",
      "autorenewStatus": "ACTIVE",
      "earliestEndDate": "2016-04-30T09:28:42Z",
      "endDate": "2016-04-30T09:28:42Z",
      "accessEndDate": "2016-04-30T15:28:42Z",
      "id": 19003,
      "price": 4,
      "initPrice": 4,
      "productName": "Basic Month",
      "productId": 429,
      "productUri": {
        "@uri": "/api/web/productgroup/449/products/429"
      },
      "productGroupId": 449,
      "paymentProviderId": 1,
      "productGroup": {
        "@uri": "/api/web/productgroup/449"
      },
      "startDate": "2016-03-30T09:28:42Z",
      "userId": 54037,
      "ip": "82.134.26.130",
      "isp": "CDN_DEMO",
      "period": 2678400,
      "periodIso": "PT2678400S",
      "platformId": 1,
      "productPaymentId": 429,
      "productPayment": {
        "@uri": "/api/web/productgroup/449/products/429/productPayments/429"
      },
      "orderRef": 19003,
      "status": "ACTIVE",
      "currency": "USD",
      "userPaymentMethod": "",
      "autorenewErrors": 0,
      "statusText": "Purchase sucessfull",
      "userStopDate": "2016-03-30T10:11:07Z",
      "registered": "2016-03-30T09:28:42Z"
    }
  }
]
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<orders>
    <order uri="/api/web/order/19003">
        <autorenewStatus>STOPPED</autorenewStatus>
        <earliestEndDate>2016-04-30T09:28:42Z</earliestEndDate>
        <endDate>2016-04-30T09:28:42Z</endDate>
        <accessEndDate>2016-04-30T15:28:42Z</accessEndDate>
        <id>19003</id>
        <price>4.0</price>
        <initPrice>4.0</initPrice>
        <productName>Basic Month</productName>
        <productId>429</productId>
        <productUri uri="/api/web/productgroup/449/products/429"/>
        <productGroupId>449</productGroupId>
        <paymentProviderId>1</paymentProviderId>
        <productGroup uri="/api/web/productgroup/449"/>
        <startDate>2016-03-30T09:28:42Z</startDate>
        <userId>54037</userId>
        <ip>82.134.26.130</ip>
        <isp>CDN_DEMO</isp>
        <period>2678400</period>
        <periodIso>PT2678400S</periodIso>
        <platformId>1</platformId>
        <productPaymentId>429</productPaymentId>
        <productPayment uri="/api/web/productgroup/449/products/429/productPayments/429"/>
        <orderRef>19003</orderRef>
        <status>ACTIVE</status>
        <currency>USD</currency>
        <userPaymentMethod/>
        <autorenewErrors>0</autorenewErrors>
        <statusText>Purchase sucessfull</statusText>
        <userStopDate>2016-03-30T10:11:07Z</userStopDate>
        <registered>2016-03-30T09:28:42Z</registered>


    </order>
</orders>

API reference: Fetch active orders

Note that in the response above there is only one active subscription, however, if you have a multi-product structure for your environment you might get more active orders returned.

It can also return a autorenewStatus": "STOPPED" subscription like in the below response, this means the client still has active access until the access end date, but the viewer has stopped the auto-renew from happening.

[
  {
    "order": {
      "@uri": "/api/web/order/19003",
      "autorenewStatus": "STOPPED",
      "earliestEndDate": "2016-04-30T09:28:42Z",
      "endDate": "2016-04-30T09:28:42Z",
      "accessEndDate": "2016-04-30T15:28:42Z",
      "id": 19003,
      "price": 4,
      "initPrice": 4,
      "productName": "Basic Month",
      "productId": 429,
      "productUri": {
        "@uri": "/api/web/productgroup/449/products/429"
      },
      "productGroupId": 449,
      "paymentProviderId": 1,
      "productGroup": {
        "@uri": "/api/web/productgroup/449"
      },
      "startDate": "2016-03-30T09:28:42Z",
      "userId": 54037,
      "ip": "82.134.26.130",
      "isp": "CDN_DEMO",
      "period": 2678400,
      "periodIso": "PT2678400S",
      "platformId": 1,
      "productPaymentId": 429,
      "productPayment": {
        "@uri": "/api/web/productgroup/449/products/429/productPayments/429"
      },
      "orderRef": 19003,
      "status": "ACTIVE",
      "currency": "USD",
      "userPaymentMethod": "",
      "autorenewErrors": 0,
      "statusText": "Purchase sucessfull",
      "userStopDate": "2016-03-30T10:11:07Z",
      "registered": "2016-03-30T09:28:42Z"
    }
  }
]

How you can make a method for users to Stop/Start subscriptions we’ll cover in the next section.

Get user’s order payment transactions

Section titled “Get user’s order payment transactions”

Get payment transactions for a specific user order, enabling better tracking and analysis.

GET /api/:platform/user/:userId/orders/:orderId/transactions
curl -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer (token)" \
  "https://api.yoursite.com/api/:platform/user/:userId/orders/:orderId/transactions"

Get all subscribed assets

Section titled “Get all subscribed assets”
GET /api/:platform/user/:userId/access/assets
curl -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer (token)" \
  "https://api.yoursite.com/api/:platform/user/:userId/access/assets"

Get all subscribed categories

Section titled “Get all subscribed categories”
GET /api/:platform/user/:userId/access/categories
curl -X GET \
  -H "Accept: application/json" \
  -H "Authorization: Bearer (token)" \
  "https://api.yoursite.com/api/:platform/user/:userId/access/categories"

Stopping or Reactivating Subscriptions

Section titled “Stopping or Reactivating Subscriptions”

After retrieving all active subscriptions it is natural to let the viewer stop or reactivate the subscriptions depending on the auto-renew status. In cases where the autorenewStatus is set to ACTIVE you likely want to add a button for stopping the subscription.

To stop a subscription you can use the below curl with an order id to stop it:

curl -X PUT \
  -H "Authorization: Bearer (token)" \
  "https://api.yoursite.com/api/:platform/order/:orderId/terminate"
{
  "order": {
    "autorenewStatus": "STOPPED",
    "earliestEndDate": "2016-04-30T09:28:42Z",
    "endDate": "2016-04-30T09:28:42Z",
    "accessEndDate": "2016-04-30T15:28:42Z",
    "id": 19003,
    "price": 4,
    "initPrice": 4,
    "productName": "Basic Month",
    "productId": 429,
    "productGroupId": 449,
    "startDate": "2016-03-30T09:28:42Z",
    "userId": 54037,
    "ip": "82.134.26.130",
    "isp": "CDN_DEMO",
    "period": 2678400,
    "periodIso": "PT2678400S",
    "platformId": 1,
    "productPaymentId": 429,
    "orderRef": 19003,
    "status": "ACTIVE",
    "currency": "USD",
    "userPaymentMethod": "",
    "autorenewErrors": 0,
    "statusText": "Purchase sucessfull",
    "userStopDate": "2016-03-30T11:09:13Z",
    "registered": "2016-03-30T09:28:42Z"
  }
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order>
    <autorenewStatus>STOPPED</autorenewStatus>
    <earliestEndDate>2016-04-30T09:28:42Z</earliestEndDate>
    <endDate>2016-04-30T09:28:42Z</endDate>
    <accessEndDate>2016-04-30T15:28:42Z</accessEndDate>
    <id>19003</id>
    <price>4.0</price>
    <initPrice>4.0</initPrice>
    <productName>Basic Month</productName>
    <productId>429</productId>
    <productGroupId>449</productGroupId>
    <startDate>2016-03-30T09:28:42Z</startDate>
    <userId>54037</userId>
    <ip>82.134.26.130</ip>
    <isp>CDN_DEMO</isp>
    <period>2678400</period>
    <periodIso>PT2678400S</periodIso>
    <platformId>1</platformId>
    <productPaymentId>429</productPaymentId>
    <orderRef>19003</orderRef>
    <status>ACTIVE</status>
    <currency>USD</currency>
    <userPaymentMethod/>
    <autorenewErrors>0</autorenewErrors>
    <statusText>Purchase sucessfull</statusText>
    <userStopDate>2016-03-30T11:09:13Z</userStopDate>
    <registered>2016-03-30T09:28:42Z</registered>
</order>

API reference: Cancel subscription

In cases where the autorenewStatus is set as STOPPED you might want to look to allow the user to reactivate the subscription. To do this you can use the below curl with the order id to reactivate the subscription again.

curl -X PUT \
  -H "Authorization: Bearer (token)" \
  "https://api.yoursite.com/api/:platform/order/:orderId/reactivate"
{
  "order": {
    "autorenewStatus": "ACTIVE",
    "earliestEndDate": "2016-04-30T09:28:42Z",
    "endDate": "2016-04-30T09:28:42Z",
    "accessEndDate": "2016-04-30T15:28:42Z",
    "id": 19003,
    "price": 4,
    "initPrice": 4,
    "productName": "Basic Month",
    "productId": 429,
    "productGroupId": 449,
    "startDate": "2016-03-30T09:28:42Z",
    "userId": 54037,
    "ip": "82.134.26.130",
    "isp": "CDN_DEMO",
    "period": 2678400,
    "periodIso": "PT2678400S",
    "platformId": 1,
    "productPaymentId": 429,
    "orderRef": 19003,
    "status": "ACTIVE",
    "currency": "USD",
    "userPaymentMethod": "",
    "autorenewErrors": 0,
    "statusText": "Purchase sucessfull",
    "userStopDate": "2016-03-30T11:09:13Z",
    "registered": "2016-03-30T09:28:42Z"
  }
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order>
    <autorenewStatus>ACTIVE</autorenewStatus>
    <earliestEndDate>2016-04-30T09:28:42Z</earliestEndDate>
    <endDate>2016-04-30T09:28:42Z</endDate>
    <accessEndDate>2016-04-30T15:28:42Z</accessEndDate>
    <id>19003</id>
    <price>4.0</price>
    <initPrice>4.0</initPrice>
    <productName>Basic Month</productName>
    <productId>429</productId>
    <productGroupId>449</productGroupId>
    <startDate>2016-03-30T09:28:42Z</startDate>
    <userId>54037</userId>
    <ip>82.134.26.130</ip>
    <isp>CDN_DEMO</isp>
    <period>2678400</period>
    <periodIso>PT2678400S</periodIso>
    <platformId>1</platformId>
    <productPaymentId>429</productPaymentId>
    <orderRef>19003</orderRef>
    <status>ACTIVE</status>
    <currency>USD</currency>
    <userPaymentMethod/>
    <autorenewErrors>0</autorenewErrors>
    <statusText>Purchase sucessfull</statusText>
    <userStopDate>2016-03-30T11:09:13Z</userStopDate>
    <registered>2016-03-30T09:28:42Z</registered>
</order>

API reference: Reactivate subscription

Subscription conversion

Section titled “Subscription conversion”

The Vimond API supports several ways of changing a subscription to a higher or lower product. What approach can be used depend solely on the payment provider used to purchase the current subscription, supporting it.

Fetching possible conversions

Section titled “Fetching possible conversions”

Defining conversion rules:

Section titled “Defining conversion rules:”

Conversion rules must be defined directly in the Oracle database, in the table PRODUCT_GROUP_UPGRADE.

📘 Database updates are handled by Vimond

Please create a ticket in the support portal

  • UPGRADE_FROM : product group id
  • UPGRADE_TO : product group id
  • UPGRADE_STRATEGY: EXTEND or DISCOUNT (Not in use)
  • ENABLED : true OR false
INSERT INTO PRODUCT_GROUP_UPGRADE (ID, UPGRADE_FROM, UPGRADE_TO, UPGRADE_STRATEGY, LAST_MODIFIED, ENABLED) VALUES (3.00000, 21.00000, 41.00000, 1.00000, sysdate, 1);

For the above entry in PRODUCT_GROUP_UPGRADE, the endpoint for fetching possible upgrades/downgrades will return products in group 21 if your current subscription has product group 41. And vice versa.

Conversions endpoint:

Section titled “Conversions endpoint:”

The conversions endpoint returns possible upgrades and downgrades for a viewer’s current and active subscriptions. A prerequisite is that the allowed conversions (on the product group level) are defined in the table PRODUCT_GROUP_UPGRADE.

One can list all possible conversion options for a viewer by doing a GET on the resource with URL
/{platform}/user/{userId}/orders/conversions

Path parameters

  • String platform,
  • Long userId

Authorization

  • Bearer token
  • or JSessionId of the viewer (Not admin user)

Query parameters:

  • orderId: The id of the order to be converted/upgraded/downgraded
  • withinCurrentProductGroup: (true || false) A boolean value stating if the response should include conversions within the same productgroup as the active current subscription. Default value is ‘false’
  • withinCurrentPaymentProviderOnly: (true || false) A boolean value stating if the endpoint should only return possible conversions within the same productgroup as the active current subscription. Default value is ‘false’
  • withinCurrentCurrencyOnly: (true || false) A boolean value stating if the endpoint should only return possible conversions within the same currency as the current active subscription. Default value is ‘false’
  • productGroupId: A list containing product group IDs for filtering which product groups that should be included in the list of possible conversions. Products in other product groups will not be included in the response.
  • productPaymentId: A list containing product payment IDs for filtering which product payments that should be included in the list of possible conversions.
  • paymentProviderId: A list containing payment provider IDs for filtering which payment providers that should be included in the list of possible conversions. ProductPayments with other payment providers will no be included in the response.
  • currency: A list containing currencies the the possible conversions should be filtered on. Products that have other currency will not be included in the response.
  • filterOperation: (UPGRADE || DOWNGRADE || ALL) DEPRECATED param. Defaults to ALL
  • filterProductPeriod: (LONGER || LONGER_OR_EQUAL || EQUAL || SHORTER_OR_EQUAL || SHORTER || ALL) A filter for specifying the allowed periods that the returned conversion-products can have compared to the current subscription
  • filterProductPayment: (ISP || ENABLED) Default value is ENABLED. Will by default only return enabled product payments.
  • showDisabled: (true || false) Will by default only return enabled product payments
  • showDiscountsOnly: (true || false) Default value is ‘false’. If set to ‘true’, the response will only contain possible conversions where the viewer will get a discount
  • trialOverride: (FORCE_TRIAL || FORCE_TRIAL_BYPASS || DEFAULT) Default value is ‘DEFAULT’. This applies configured trial price and period. If set to ‘FORCE_TRIAL’, both init period and init price of the products will be used. If set to ‘FORCE_TRIAL_BYPASS’, the product’s period and price will be used. Also the OrderFreeTrialLimit option will be overridden by this query parameter.

Output

<orderConversionList>
    <orderConversion>
        <orderConversionProductGroup>
            <productGroup id="42" uri="/api/web/productgroup/42">
                <name>3. Sport</name>
                <sortIndex>1</sortIndex>
                <categories uri="/api/web/productgroup/42/categories"/>
                <accessType>PAID</accessType>
                <metadata uri="/api/metadata/productgroup/42"/>
                <products uri="/api/web/productgroup/42/products"/>
                <saleStatus>ENABLED</saleStatus>
                <checkAccessForProgramRelations>false</checkAccessForProgramRelations>
            </productGroup>
            <orderConversionProduct>
                <product id="34" uri="/api/web/productgroup/43/products/34">
                    <paymentPlan id="22">
                        <name>Month</name>
                        <period>2678400</period>
                        <periodIso>PT2678400S</periodIso>
                        <paymentType>SUBSCRIPTION</paymentType>
                    </paymentPlan>
                    <description>Total month</description>
                    <enabled>true</enabled>
                    <minimumPeriods>0</minimumPeriods>
                    <price>3100.0</price>
                    <productGroupId>43</productGroupId>
                    <sortIndex>1</sortIndex>
                    <productPaymentsUri uri="/api/web/productgroup/43/products/34/productPayments"/>
                    <currency>NOK</currency>
                    <productStatus>ENABLED</productStatus>
                </product>
                <orderConversionProductPayment>
                    <productPayment id="197" uri="/api/web/productgroup/43/products/34/productPayments/197">
                        <enabled>true</enabled>
                        <initPeriod>2678400</initPeriod>
                        <initPeriodIso>PT2678400S</initPeriodIso>
                        <initPrice>3100.0</initPrice>
                        <paymentProviderId>1</paymentProviderId>
                        <productId>34</productId>
                        <sortIndex>0</sortIndex>
                        <productPaymentStatus>ENABLED</productPaymentStatus>
                        <paymentObjectUri uri="/api/web/productgroup/43/products/34/productPayments/197/payment"/>
                        <autorenewWarningChannel>EMAIL</autorenewWarningChannel>
                        <autoRenewWarningEnabled>false</autoRenewWarningEnabled>
                    </productPayment>
                    <originalPrice>3100</originalPrice>
                    <price>2520</price>
                    <discount>580</discount>
                    <time>2678400</time>
                    <extendedTime>501120</extendedTime>
                    <discountAvailable>true</discountAvailable>
                    <convertOrderCapabilities>Supported</convertOrderCapabilities>
                    <oneClickBuyCapabilities>Supported</oneClickBuyCapabilities>
                    <purchaseWithoutPaymentInfoCapabilities>NotSupported</purchaseWithoutPaymentInfoCapabilities>
                    <changeOperation>UPGRADE</changeOperation>
                    <trialOverride>DEFAULT</trialOverride>
                    <orderConversionWithinSamePeriod>
                        <capabilities>Supported</capabilities>
                        <remainingSecondsOfCurrentPeriodFromEndOfToday>1339200</remainingSecondsOfCurrentPeriodFromEndOfToday>
                        <priceForRemainingOfCurrentPeriodWithoutDiscount>1550</priceForRemainingOfCurrentPeriodWithoutDiscount>
                        <discount>580</discount>
                        <numberOfFullPeriodsAdded>0</numberOfFullPeriodsAdded>
                        <priceToPay>970</priceToPay>
                        <endDate>2018-12-02T23:49:09Z</endDate>
                        <initPeriodInSeconds>1339200</initPeriodInSeconds>
                    </orderConversionWithinSamePeriod>
                </orderConversionProductPayment>
            </orderConversionProduct>
        </orderConversionProductGroup>
        <orderId>6076001018</orderId>
    </orderConversion>
</orderConversionList>
  • The endpoint returns an orderConversionList containing up to several orderConversions. An orderConversion can contain up to several orderConversionProductGroups. An orderConversionProductGroup can contain up to several orderConversionProducts in addition to the referenced productGroup. An orderConversionProduct can contain up to several orderConversionProductPayments in addition to the referenced product. An orderConversionProductPayment contains the referenced productPayment and the following information:
  • originalPrice - The original price of the product
  • price - The lowest price to be paid. If a discount is available, the value will be the original price subtracted by the discount. If not, it will be equal to the original price
  • discount - Present if a discount is available. Is calculated by multiplying the price the customer paid for the original order with the fraction of how much time there is left of the period.
  • extendedTime - The amount of extended time on the new subscription. Is calculated based on the amount of access the customer has paid for but not received if the current subscription is converted instantly.
    For both discount and extendedTime the value is calculated using the full price for the remaining access of the current subscription. A feature toggle exists that will calculate the current value of a free trial to zero. If you want this to be enabled in your environment, please contact Vimond Customer Support
  • time - The length of the product period
  • discountAvailable - Value of true if discount > 0
  • convertOrderCapabilities - Value is Supported if the payment provider supports it. A prerequisite is that we store payment information and that it can be transferred to a new order.
  • oneClickBuyCapabilities - Value is Supported if the payment provider supports one click buy.
  • purchaseWithoutPaymentInfoCapabilities - Value is Supported if a purchase can be made with the given payment provider without providing payment information.
  • changeOperation - Values:
    -UPGRADE
    Product belongs to a different product group than the current subscription
    Product currency is the same as the current subscription is purchased with
    Product price is more expensive than the current subscription
    -DOWNGRADE
    Product belongs to a different product group than the current subscription
    Product currency is the same as the current subscription is purchased with
    Product price is less expensive than the current subscription
    -CROSSGRADE
    Product belongs to the same product group as the current subscription or product price is equal to the
    price of the current subscription
    Product currency is the same as the current subscription is purchased with
    -PRODUCT_AND_CURRENCY_CHANGE
    Product currency is different from the one the current subscription is purchased with. In this case,
    neither extended time nor discount will be available

In addition, the orderConversionProductPayment includes a structure called orderConversionWithinSamePeriod which contains info about the properties relevant for instant order upgrade/downgrade in which the enddate of the current order is transferred to the new one. If priceToPay is a negative number, an additional period is added to the enddate. The structure contains the following:

  • capabilities - Value is Supported if converting to that specific product is possible within the current period of the subscription, NotSupported if not, and SupportedWithAddedPeriod if the operation is supported with an added period to the enddate.
  • remainingSecondsOfCurrentPeriodFromEndOfToday - The number of seconds left of the current subscription from end of today
  • priceForRemainingOfCurrentPeriodWithoutDiscount - The new products price for the remaining of the period of the current subscription
  • discount - Is calculated by multiplying the price the customer paid for the original order with the fraction of how much time there is left of the period.
  • numberOfFullPeriodsAdded - The number of periods added to the enddate
  • priceToPay - The price to pay for the conversion
  • endDate - The enddate of the new subscription if conversion is done
  • initPeriodInSeconds - The initial period in seconds of the new subscription if conversion is done

Convert Order For Next Renewal

Section titled “Convert Order For Next Renewal”

The logic behind this approach is that the actual conversion happens at renewal. The existing order will be stopped by setting autorenewStatus=CONVERTED, but the order will keep its end date and access end date. The new order will have a start date, end date, access end date, and earliest end date set to the same as the original order’s end date. It will also inherit the old subscription’s user_payment_method. When the old subscription expires the new order will be renewed and the viewer will be on a new subscription with renewed access.

Prerequisites:

  • The payment provider used to purchase both the current and the new subscription must match. The reason for this is that the payment information will be transferred
  • The payment provider must support the operation. This is indicated by the field convertOrderCapabilities (value must be Supported) in the response returned by the above-mentioned conversions endpoint

Payment provider not supporting it:

  • Itunes
  • Google Play
  • TPay
  • Bluesnap
  • Nets Direct Bank

PUT /api/web/order/

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order>
    <userId>{userId}</userId>
    <productPaymentId>{productPaymentId}</productPaymentId>
    <payment>
        <orderId>{ID of the order to be converted}</orderId>
        <paymentMethod>CONVERT_ORDER_FOR_NEXT_RENEWAL</paymentMethod>
    </payment>
</order>

Instant conversion

Section titled “Instant conversion”

With instant conversion, just like with conversion at renewal, the payment information will be transferred from the current subscription to the new one. But unlike conversion at renewal, the conversion happens instantly. The initial period of the new subscription will be set to the extended time that is owed to the viewer.

Prerequisites:

  • The payment provider used to purchase both the current and the new subscription must match. The reason for this is that the payment information will be transferred
  • The payment provider must support the operation. This is indicated by the field convertOrderCapabilities (value must be Supported) in the response returned by the above-mentioned conversions endpoint
  • The currencies used to purchase the old subscription must match the new product. If currencies don’t match, the value of the field changeOperation in the response returned by the above-mentioned conversions endpoint will be PRODUCT_AND_CURRENCY_CHANGE.

Payment provider not supporting it:

  • Itunes
  • Google Play
  • TPay
  • Bluesnap
  • Nets Direct Bank

PUT /api/web/order/

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order>
    <userId>{userId}</userId>
    <productPaymentId>{productPaymentId}</productPaymentId>
    <payment>
        <orderId>{ID of the order to be converted}</orderId>
        <paymentMethod>CONVERT_ORDER_INSTANTLY</paymentMethod>
    </payment>
</order>

Upgrade/downgrade via one-click buy

Section titled “Upgrade/downgrade via one-click buy”

The concept of a one-click buy is to reuse existing payment credentials in order to make a new purchase. By referencing an existing subscription when making the purchase, an instant upgrade or downgrade can be made. If no viewer payment method is given in the request, the one used in the current subscription will be reused.
When making the subscription change, the viewer can choose one of the three upgrade options ‘DISCOUNT’, ‘EXTENDED_TIME’, and ‘CONVERT_WITHIN_SAME_PERIOD’. If a discount is available (indicated in the response from the conversions endpoint), it will be applied to the initial price of the product. If ‘EXTENDED_TIME’ is available and selected, it will be applied to the initial period of the product. If ‘CONVERT_WITHIN_SAME_PERIOD’ is available and selected, the enddate of the current order is transferred to the new one if the calculated priceToPay is a positive number. If priceToPay is a negative number, an additional period is added to the enddate

Prerequisites

  • The payment provider used to purchase both the current and the new subscription must match. The reason for this is that the payment information will be transferred
  • The payment provider must support the operation. This is indicated by the field oneClickBuyCapabilities (value must be Supported) in the response returned by the above-mentioned conversions endpoint
  • The currencies used to purchase the old subscription must match the new product. If currencies don’t match, the value of the field changeOperation in the response returned by the above-mentioned conversions endpoint will be PRODUCT_AND_CURRENCY_CHANGE.
  • During the subscription change, the viewer must specify ‘DISCOUNT’, ‘EXTENDED_TIME’, or ‘CONVERT_WITHIN_SAME_PERIOD’ as upgradeOption. Upgrade Options must be available in order to be allowed to perform the operation.

Supported by payment providers:

  • Nets
  • Dibs
  • Altapay
  • Klarna

PUT /api/web/order/
Optional queryParam: trialOverride (FORCE_TRIAL || FORCE_TRIAL_BYPASS || DEFAULT)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<order>
    <userId>{userId}</userId>
    <productPaymentId>{productPaymentId}</productPaymentId>
    <payment>
        <paymentMethod>ONE_CLICK_BUY</paymentMethod>
        <password>{user password if required}</password>
    </payment>
  <upgradeOrderId>{The ID of the order to be upgraded}</upgradeOrderId>
  <upgradeOption>{EXTENDED_TIME || DISCOUNT || CHANGE_PAYMENT_INFO || CONVERT_WITHIN_SAME_PERIOD}</upgradeOption>
  <userPaymentMethod> <!--Optional param -->
    <id>{UserPaymentMethodId}</id>
  </userPaymentMethod
</order>

Upgrade downgrade via regular purchase (re-registering payment information)

Section titled “Upgrade downgrade via regular purchase (re-registering payment information)”

It is possible to both upgrade and downgrade subscriptions without reusing existing credit cards and other payment credentials. By including upgradeOrderId and upgradeOption in the request, an existing order can be upgraded/downgraded by going through the normal purchase flow.
When making the subscription change, the viewer can choose one of the three upgrade options ‘DISCOUNT’, ‘EXTENDED_TIME’, and ‘CONVERT_WITHIN_SAME_PERIOD’. If a discount is available, it will be applied to the initial price of the product. If ‘EXTENDED_TIME’ is available and selected, it will be applied to the initial period of the product. If ‘CONVERT_WITHIN_SAME_PERIOD’ is available and selected, the enddate of the current order is transferred to the new one if the calculated priceToPay is a positive number. If priceToPay is a negative number, an additional period is added to the enddate. For checking the available conversion -and upgradeOption possibilities, please read https://developer.vimond.com/docs/subscriptions#section-fetching-possible-conversions

Please seek documentation of the given payment provider for more information.

Payment provider not supporting subscription change:

  • Itunes
  • Google Play
  • TPay
  • Bluesnap
  • Nets Direct Bank

SVOD and VIA Entitlement claims

Section titled “SVOD and VIA Entitlement claims”

If using your own IAM, please ensure https://vimond/entitlements claims are included in JWT tokens.

An example of using the svod property with a comma-separated list of content package identifiers 54 and 77;

"https://vimond/entitlements": [
      "svod": "54,77",
      ...
]

The svod IDs are mapped to the Vimond internal package id in the play flow.

For more details and examples please see Custom Entitlement claims

SVOD and VIA Viewer Facing Services

Section titled “SVOD and VIA Viewer Facing Services”

With VIA IAM or your own IAM where you have added the svod entitlement, users can effortlessly access content using the Play service API used for Video Playback.

This guide empowers developers to seamlessly integrate SVOD into their platforms, providing users with subscription-based content access while enabling content providers to generate revenue. By following these steps, you can create a robust and user-friendly SVOD experience.

SVOD and VIA Data

Section titled “SVOD and VIA Data”

All user subscriptions are part of the daily delta and snapshot of user access and as events using VIA Data Event Stream.