Cancelling an account (third-party products)

Overview

When an entitlement needs to be cancelled (for example, if the customer does not renew, or if their payment fails), the self-service portal must call OpenTV Platform to change the status of the entitlement to cancelled.

OpenTV Platform then calls Bango to cancel the subscription.

Request

To change the status of a third-party product entitlement to cancelled, the self-care portal should send a POST request to:

BASH

https://<host>:<port>/tpes/v1/operator/entitlements/{entitlementId}/actions/cancel

Headers

x-correlation-id – identifier for logging, to correlate messages across a call flow
Authorization – Keycloak access token (see Accessing operator APIs using Keycloak)
nv-tenant-id – the tenant ID

Mandatory arguments

entitlementId (in the URL) – the ID of the entitlement to be suspended
cancelReasonCode (in body) – the reason for the cancellation. See the TPES API documentation for the list of reasons.
cancelReasonCategory (in body) – the reason category. See the TPES API documentation for the list of reason categories.

Optional arguments

cancelReasonDescription (in body) – description of the cancellation reason (e.g., “The user did not renew the monthly contract”).

Example

A request with the following body cancels the entitlement whose ID is specified in the URL:

JSON

{
  "cancelReasonCategory": "CUSTOMER_CANCELLED",
  "cancelReasonCode": "NOT_RENEWED",
  "cancelReasonDescription": "The user did not renew the monthly contract"
}

Response

A successful request returns an HTTP 200 status.

If the request is awaiting confirmation from the third-party provider, the request returns an HTTP 202 status.

A bad request returns an HTTP 400 status.

If the specified entitlement does not exist, the request returns an HTTP 404 status.