Platform-Managed APIs

This page contains information about the MarketONE APIs that the Merchant needs to implement for integration with Partner Ecosystem Management for the Platform-managed flow. The APIs include:

Standard APIs (All Required)
Webhooks (Add and Delete Subscription Webhooks Required)

On this page, you can find API definitions, example requests, internal implementation instructions, and example responses.

Standard APIs
Webhooks

Parent topic:Design Guidelines for the Platform-Managed Flow

Standard APIs

The following APIs are required for the Platform-managed integration:

PUT /partnerSubscription/{id}
GET /subscription/{id}/partner/status Note: Merchants aren’t required to make the GET /subscription/{id}/partner/status call. Merchants only need to provide a response.

Update Partner Subscription Status API

The Merchant uses PUT /partnerSubscription/{id} to update the partnerSubscription status after the Merchant has activated the user’s subscription (based on the partnerSubscriptionID as the Id parameter). Note: As of May 2021, v3 is used for this API.

{
   "serviceStatus": "ACTIVE" //The status for this call will always be active
}

For more information about this request, see the MarketONE OpenAPI.

Get Partner Subscription Status API

MarketONE uses GET /subscription/{id}/partner/status to get the partnerSubscription status from the Merchant. The Merchant is required to provide a response. Response At minimum, the Merchant should return the partnerSubscriptionId and status in the response body. Here’s an example of the response body MarketONE expects to receive from the Merchant:

{
   "partnerSubscriptionId":"<MarketONE OpenAPI unique id for the partner subscription and the user>",
   "partnerCustomerId":"<Unique identifier for a customer>",
   "partnerCode":"string",
   "productCode":"<Pre-defined product code of the Merchant's product>",
   "status":"string",
   "metadata":{
      "property1":"string",
      "property2":"string"
   }

For more information about this request, see the OTT Service Callbacks. Parent topic:Platform-Managed APIs

Webhooks

The Merchant webhooks are automatically generated API requests that allow a Merchant system to know about Partner Ecosystem Management service provisioning events as they occur. You can provide a webhook endpoint URL and when those events happen, Partner Ecosystem Management will automatically generate an HTTPS POST request with a JSON payload. Partner Ecosystem Management webhook actions will include the full related object(s) in JSON format. Merchants need to add webhooks to receive the webhook events. After adding the webhooks, Merchants are required to process the webhook events, internally implement changes, and respond with a call to the MarketONE OpenAPI to update the partnerSubscription status. Note: You must add one API key per Reseller in Partner Ecosystem Management for machine-to-machine authentication. Include the corresponding Reseller-specific API key in the HTTP header of the Partner Ecosystem Management webhook. Information in this section is provided about the following MarketONE webhooks:

Add Subscription (Required)
Update Subscription - Downgrade or Upgrade
Delete Subscription (Required)
Update Subscription Metadata
Pause Subscription
Resume Subscription

For the complete details about these webhooks, see the MarketONE OTT Service Callbacks.

Add Subscription (Required)

MarketONE sends the Add Subscription event when the customer purchases a subscription from the Reseller’s (Service Provider’s) website, or a subscription needs to be re-provisioned. Request Here’s an example of an Add Subscription request body:

{
   "action":"AddSubscription",
   "subscriptionId":"<MarketONE OpenAPI SubscriptionId>", //The Merchant can ignore this ID
   "partnerSubscriptionId":"<MarketONE OpenAPI unique ID for the new partner subscription and the user>",
   "organizationCode":"<organization code of the Reseller where the new subscription is originated>",
   "partnerCustomerId":"<optional field. A unique identifier for a customer. If a customer cancels the original subscription and resubscribes then this ID will be the same>",
   "productCode":"<Pre-defined product code of the Merchant's product>",
   "registrationString":"<Redemption Code>"
}

Notes on redemption code expiration time:

If the redemption code (registrationString) is generated by MarketONE, MarketONE can optionally configure its expiration time (redemptionCodeExpirationTime):
1. MarketONE calls the AddSubscription callback and sends the redemption code along with the configured expiration time.
2. MarketONE sends the redemption code and its expiration time to the Reseller (Service Provider) notification (which the Reseller could then send as a notification to the user).
3. The Merchant is responsible for letting the user activate their subscription if the redemption code hasn’t expired.
4. If the redemption code has expired, the user needs to request a new redemption code via the Reseller making a POST /partnerSubscription/{id}/reprovision call.
If the redemption code (registrationString) is generated by the Merchant (enabled using the Partner Ecosystem Management UI), the Merchant needs to send back the redemption code in response to the AddSubscription callback along with the optional expiration time (redemptionCodeExpirationTime):
1. MarketONE forwards the redemption code and the expiration time to the Reseller (Service Provider) notification.
2. The Merchant is responsible for letting the user activate their subscription if the redemption code hasn’t expired.
3. If the redemption code has expired, the user needs to request a new redemption code using the re-provisioning API.
If redemptionCodeExpirationTime is not set, the redemption code is treated as non-expiring.

Internal Implementation and Response to MarketONE (New Subscription) Perform the following steps:

Upon receiving the MarketONE callback, create a new entry for the new subscription, and keep the information from the request body (including the partnerSubscriptionID, productCode, redemption code (registrationString), etc.). The start date/time should be counted when the Merchant receives the MarketONE callback.
Send the new entry id as externalPartnerSubscriptionID in the response to MarketONE (with the status as INACTIVE).

Here’s an example of an Add Subscription response body:

{
   "subscriptionId":"<subscriptionId from the MarketONE callback request>",
   "partnerSubscriptionId":"<partnerSubscriptionID received from AddSubscription callback request>"
   "externalPartnerSubscriptionId":"<corresponding unique subscription ID generated by the Merchant>",
   "registrationStatus":"INACTIVE", //The status must be Inactive
}

Internal Implementation and Response to MarketONE (Re-provisioned Subscription) Re-provisioning happens when the user requests that the redemption link be re-sent. This can occur because the user purchased the Merchant’s subscription but didn’t receive the redemption link (through email or SMS) or the launch button is not active on the STB (set-top box). The re-sending of the redemption link will trigger the same AddSubscription callback to the Merchant. However, it will have the existing partnerSubscriptionID and a newly generated redemption code (registrationString) from MarketONE. Perform the following steps:

The Merchant receives the MarketONE callback with the AddSubscription action. If the Merchant finds the same partnerSubscriptionID in the request, it means it’s a re-provision.
The Merchant should replace the existing redemption code of this particular Merchant subscription with the new one from the callback request.

Here’s an example of an Add Subscription response body:

{
   "subscriptionId":"<subscriptionId from the MarketONE callback request>",
   "partnerSubscriptionId":"<partnerSubscriptionID received from AddSubscription callback request>"
   "externalPartnerSubscriptionId":"<corresponding unique subscription ID generated by the Merchant>",
   "registrationStatus":"INACTIVE", //The status must be Inactive
}

Update Subscription - Downgrade or Upgrade

MarketONE sends the Update Subscription event when the customer upgrades or downgrades the service subscription via the Reseller’s (Service Provider’s) website. Request Here’s an example of an Update Subscription request body:

{
   "action":"UpdateSubscription",
   "subscriptionId":"<MarketONE OpenAPI SubscriptionId>", //The Merchant can ignore this ID
   "partnerSubscriptionId":"<Existing partner subscription ID>",
   "organizationCode":"<organization code of the Reseller where the new subscription is originated>"
   "productCode":"<Pre-defined productCode of the Merchant's product>", // This will be a different code from the original product code
   "partnerCustomerId":"<optional field. A unique identifier for a customer>"
}

Internal Implementation and Response to MarketONE Perform the following steps:

Find the matching entry of the partnerSubscriptionID from the request body.
Replace the old product code with the new product code.
Grant the user access to the new (upgrade/downgrade) product.

Here’s an example of an Update Subscription response body:

{
   "partnerSubscriptionId":"<partnerSubscriptionID received from UpdateSubscription callback request>"
   "externalPartnerSubscriptionId":"<corresponding unique subscription ID generated by the Merchant>",
   "registrationStatus":"ACTIVE", //In most cases the user updates an existing active subscription,
   however in cases where the user hasn't activated the original subscription but wants to upgrade/downgrade in the meantime, Partner Ecosystem Management supports it as well, although here the status should be INACTIVE
}

Delete Subscription (Required)

MarketONE sends the Delete Subscription event when the customer cancels the subscription or the subscription is no longer valid based on the status of the customer’s billing account. Request Here’s an example of a Delete Subscription request body:

{
   "action":"DeleteSubscription",
   "subscriptionId":"<subscriptionId from MarketONE callback request>",
   "partnerSubscriptionId":"<MarketONE OpenAPI unique ID for an existing partner subscription the user wants to cancel>",
   "externalPartnerSubscriptionId":"<Unique user subscription ID from the Merchant>",
   "partnerCustomerId":"<optional field. A unique identifier for a customer>"
}

Internal Implementation and Response to MarketONE Perform the following steps:

Find the matching entry of the partnerSubscriptionID from the request body.
Mark the subscription status as CANCELLED (or equivalent).
Send the response to MarketONE (with the status as INACTIVE).

Here’s an example of a Delete Subscription response body:

{
   "partnerSubscriptionId":"<same partnerSubscriptionId from the DeleteSubscription callback request >",
   "externalPartnerSubscriptionId":"<Unique user subscription ID from the Merchant>",
   "registrationStatus":"CANCELLED"
}

Update Subscription Metadata

MarketONE sends the Update Subscription Metadata event when any metadata associated with a subscription is changed on the Reseller’s (Service Provider’s) side, such as a phone number. Request Here’s an example of an Update Subscription Metadata request body:

{
   "action":"UpdateSubscriptionMetadata",
   "subscriptionId":"<The ID of a MarketONE subscription. Will be sent in the request call for AddSubscription>",
   "partnerSubscriptionId":"<MarketONE OpenAPI unique ID for an existing partner subscription with metadata the user wants to update>",
   "partnerCustomerId":"<The unique identifier for the partner customer account>",
   "externalPartnerSubscriptionId":"<Unique user subscription ID from the Merchant>",
   "organizationCode":"<The organization code for the Reseller (Service Provider)>",
   "productCode":"<The code of the Merchant product subscribed by the customer as defined by the Merchant in Partner Ecosystem Management>",
   "metadata":{
      "property1":"string",
      "property2":"string"
   }
}

Internal Implementation and Response to MarketONE Here’s an example of an Update Subscription Metadata response body:

{
   "partnerSubscriptionId":"<MarketONE OpenAPI unique ID for the existing partner subscription>",
   "partnerCustomerId":"<The unique identifier for the partner customer account>",
   "externalPartnerSubscriptionId":"<Unique user subscription ID from the Merchant>"
}

Pause Subscription

MarketONE sends the Pause Subscription event when a customer’s subscription is paused from the Reseller’s (Service Provider’s) side for a variety of reasons, such as non-pay scenarios. Request Here’s an example of a Pause Subscription request body:

{
   "action":"PauseSubscription",
   "partnerSubscriptionId":"<MarketONE OpenAPI unique ID for an existing partner subscription the user wants to pause>"
}

Response Here’s an example of a Pause Subscription response body:

{
   "partnerSubscriptionId":"<same partnerSubscriptionId from the PauseSubscription callback request >",
   "registrationStatus":"PAUSED"
}

Resume Subscription

MarketONE sends the Resume Subscription event when a customer’s paused subscription is resumed from the Reseller’s (Service Provider’s) side. Request Here’s an example of a Resume Subscription request body:

{
   "action":"ResumeSubscription",
   "partnerSubscriptionId":"<MarketONE OpenAPI unique ID for an existing partner subscription the user wants to resume>"
}

Response Here’s an example of a Resume Subscription response body:

{
   "partnerSubscriptionId":"<same partnerSubscriptionId from the ResumeSubscription callback request >",
   "registrationStatus":"ACTIVE" <Or INACTIVE, depends on the original status of the partner subscription at the time the subscription is paused>
}

Parent topic:Platform-Managed APIs

Home

Introduction

For Merchants

For Resellers

Partner Ecosystem Management

Commerce Engine

Storefront Experience

APIs

Standard APIs

Update Partner Subscription Status API

Get Partner Subscription Status API

Webhooks

Add Subscription (Required)

Update Subscription - Downgrade or Upgrade

Delete Subscription (Required)

Update Subscription Metadata

Pause Subscription

Resume Subscription

​Standard APIs

​Update Partner Subscription Status API

​Get Partner Subscription Status API

​Webhooks

​Add Subscription (Required)

​Update Subscription - Downgrade or Upgrade

​Delete Subscription (Required)

​Update Subscription Metadata

​Pause Subscription

​Resume Subscription

Standard APIs

Update Partner Subscription Status API

Get Partner Subscription Status API

Webhooks

Add Subscription (Required)

Update Subscription - Downgrade or Upgrade

Delete Subscription (Required)

Update Subscription Metadata

Pause Subscription

Resume Subscription