Cancelling a third-party product entitlement – non-SSP deployment

Request

To cancel a third-party product entitlement, the CRM system should send a PUT 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 (25.12_Q1) Accessing operator APIs using Keycloak)
nv-tenant-id – the tenant ID

Mandatory arguments

entitlementId (in URL) – the ID of the entitlement to be cancelled
cancelReasonCategory (in body) – the cancellation reason category (see table below)
cancelReasonCode (in body) – the cancellation reason code (see table below)

Valid cancellation categories and reasons are as follows:

Category	Reason code
`CUSTOMER_CANCELLED`	`NOT_RENEWED`
	`CUSTOMER_CANCELLED`
	`EXPIRED`
	`CHANGED_SERVICE`
	`SUBSCRIPTION_CANCELLED`
	`ADDON_CANCELLED`
	`OTHER`
`CUSTOMER_CHANGED`	`CUSTOMER_CANCELLED_BUNDLE`
`CUSTOMER_CHANGED`	`CHANGED_SERVICE`
`ACTIVATION_ROLLBACK`	`FRAUD`
	`CUSTOMER_PAYMENT_DEFAULT`
	`FRAUD_CHECK`
	`MERCHANT_ACCOUNT_CHANGED`
`REVOKED`	`OTHER`
	`ROLLBACK_ERROR`
	`ROLLBACK_CONNECT_ERROR`
	`PRODUCT_NO_LONGER_AVAILABLE`
	`PARTNER_RETURN`
	`CUSTOMER_RETURN`
	`ACCOUNT_TERMINATED`
	`SUSPEND_TERMINATED`
	`ERROR`
	`FRAUD`
	`IMMEDIATE_CANCELLATION`

Optional arguments

cancelReasonDescription – a description of the cancellation reason

Example

A POST request with the following body will update the status of 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. When OPF receives this confirmation, it notifies your CRM system – see Implementing endpoints to handle notification and authorisation calls from OPF.

A bad request returns an HTTP 400 status.

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

See the Third Party Entitlement Service (TPES) API documentation for the specific error codes and their meanings.