Terminate an entitlement

curl --request POST \
  --url https://virtserver.swaggerhub.com/BangoProducts/MerchantInterface_Server_API/1.1.0/v1/merchant/entitlement/terminate/{merchantEntitlementId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "terminatedDate": "2019-10-14T15:34:49Z"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({terminatedDate: '2019-10-14T15:34:49Z'})
};

fetch('https://virtserver.swaggerhub.com/BangoProducts/MerchantInterface_Server_API/1.1.0/v1/merchant/entitlement/terminate/{merchantEntitlementId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://virtserver.swaggerhub.com/BangoProducts/MerchantInterface_Server_API/1.1.0/v1/merchant/entitlement/terminate/{merchantEntitlementId}"

payload = { "terminatedDate": "2019-10-14T15:34:49Z" }
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "responseCode": "OK",
  "responseMessage": "Success",
  "requestId": "981a55a5-b3a4-46dc-9fac-a86227b26344",
  "bangoUserId": "1549053185",
  "sharedCustomerId": "414b3019-0c28-4d14-9c5f-6217b8bd1e3e",
  "productId": "30_DAYS_MUSIC",
  "offerId": "FREE_FOR_6_MONTHS",
  "resellerId": "XYZ_RESELLER",
  "customerId": "<string>",
  "status": "REVOKED",
  "dateCreated": "2023-11-07T05:31:56Z",
  "dateActivated": "2023-11-07T05:31:56Z",
  "dateExpiry": null,
  "dateEnded": "2023-11-07T05:31:56Z",
  "dateSuspended": null,
  "dateResumed": null,
  "dateAutoSuspend": null,
  "merchantExtensionData": {
    "merchantCustomData1": "merchantCustomDataValue1",
    "merchantCustomData2": "merchantCustomDataValue2",
    "merchantCustomData3": "merchantCustomDataValue3"
  },
  "extraInformation": {
    "clientDevice": {
      "type": "STB",
      "id": "bc449c9e-406f-4399-a3ff-8671a27ac410",
      "typeId": "P49AJFND8NFN23NANGAJG",
      "modelName": "STB Model X7",
      "modelNumber": "IAH45IAOF/5",
      "serialNumber": "JHFJHA43JNFA9393GFD",
      "osType": "Linux",
      "osVersion": "10.3.8",
      "macAddress": "4A-0F-99-F2-D3-DD",
      "browser": "Firefox"
    },
    "communicationInformation": {
      "emailAddress": "123@abc.co.uk",
      "msisdn": "441234567890"
    },
    "source": {
      "channelType": "WEB_PROMOTION",
      "campaignRef": "SUMMER_PROMO",
      "referrer": "SEARCH_ENGINE",
      "bundleId": "BundleABC123",
      "country": "United Kingdom",
      "region": "East Anglia",
      "brand": "BrandABC",
      "serviceFlow": "Creation"
    }
  },
  "financeData": {
    "source": "Merchant",
    "type": "order",
    "timestamp": "2023-11-07T05:31:56Z",
    "retailCurrency": "<string>",
    "retailPrice": 123,
    "retailPriceTax": 123,
    "offerPrice": 123,
    "offerPriceTax": 123,
    "notes": "<string>"
  },
  "merchantBangoExtensionData": {
    "merchantCustomData1": "merchantBangoCustomDataValue1",
    "merchantCustomData2": "merchantBangoCustomDataValue2",
    "merchantCustomData3": "merchantBangoCustomDataValue3"
  }
}

{
  "responseCode": "BAD_REQUEST",
  "responseMessage": "Invalid request"
}

{
  "responseCode": "UNAUTHORIZED",
  "responseMessage": "You have not provided adequate credentials to access this resource."
}

{
  "responseCode": "NOT_FOUND",
  "responseMessage": "Entitlement not found"
}

{
  "responseCode": "INVALID_STATE",
  "responseMessage": "Operation invalid for the current state of the entitlement."
}

{
  "responseCode": "TOO_MANY_REQUESTS",
  "responseMessage": "Request limit reached. Please try again later"
}

{
  "responseCode": "INTERNAL_ERROR",
  "responseMessage": "The server encountered an unexpected condition which prevented it from fulfilling the request"
}

{
  "responseCode": "SERVICE_UNAVAILABLE",
  "responseMessage": "The server is undergoing maintenance and is not available. Please, try again later"
}

POST

https://virtserver.swaggerhub.com/BangoProducts/MerchantInterface_Server_API/1.1.0

merchant

entitlement

terminate

{merchantEntitlementId}

Terminate an entitlement

curl --request POST \
  --url https://virtserver.swaggerhub.com/BangoProducts/MerchantInterface_Server_API/1.1.0/v1/merchant/entitlement/terminate/{merchantEntitlementId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "terminatedDate": "2019-10-14T15:34:49Z"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({terminatedDate: '2019-10-14T15:34:49Z'})
};

fetch('https://virtserver.swaggerhub.com/BangoProducts/MerchantInterface_Server_API/1.1.0/v1/merchant/entitlement/terminate/{merchantEntitlementId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://virtserver.swaggerhub.com/BangoProducts/MerchantInterface_Server_API/1.1.0/v1/merchant/entitlement/terminate/{merchantEntitlementId}"

payload = { "terminatedDate": "2019-10-14T15:34:49Z" }
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "responseCode": "OK",
  "responseMessage": "Success",
  "requestId": "981a55a5-b3a4-46dc-9fac-a86227b26344",
  "bangoUserId": "1549053185",
  "sharedCustomerId": "414b3019-0c28-4d14-9c5f-6217b8bd1e3e",
  "productId": "30_DAYS_MUSIC",
  "offerId": "FREE_FOR_6_MONTHS",
  "resellerId": "XYZ_RESELLER",
  "customerId": "<string>",
  "status": "REVOKED",
  "dateCreated": "2023-11-07T05:31:56Z",
  "dateActivated": "2023-11-07T05:31:56Z",
  "dateExpiry": null,
  "dateEnded": "2023-11-07T05:31:56Z",
  "dateSuspended": null,
  "dateResumed": null,
  "dateAutoSuspend": null,
  "merchantExtensionData": {
    "merchantCustomData1": "merchantCustomDataValue1",
    "merchantCustomData2": "merchantCustomDataValue2",
    "merchantCustomData3": "merchantCustomDataValue3"
  },
  "extraInformation": {
    "clientDevice": {
      "type": "STB",
      "id": "bc449c9e-406f-4399-a3ff-8671a27ac410",
      "typeId": "P49AJFND8NFN23NANGAJG",
      "modelName": "STB Model X7",
      "modelNumber": "IAH45IAOF/5",
      "serialNumber": "JHFJHA43JNFA9393GFD",
      "osType": "Linux",
      "osVersion": "10.3.8",
      "macAddress": "4A-0F-99-F2-D3-DD",
      "browser": "Firefox"
    },
    "communicationInformation": {
      "emailAddress": "123@abc.co.uk",
      "msisdn": "441234567890"
    },
    "source": {
      "channelType": "WEB_PROMOTION",
      "campaignRef": "SUMMER_PROMO",
      "referrer": "SEARCH_ENGINE",
      "bundleId": "BundleABC123",
      "country": "United Kingdom",
      "region": "East Anglia",
      "brand": "BrandABC",
      "serviceFlow": "Creation"
    }
  },
  "financeData": {
    "source": "Merchant",
    "type": "order",
    "timestamp": "2023-11-07T05:31:56Z",
    "retailCurrency": "<string>",
    "retailPrice": 123,
    "retailPriceTax": 123,
    "offerPrice": 123,
    "offerPriceTax": 123,
    "notes": "<string>"
  },
  "merchantBangoExtensionData": {
    "merchantCustomData1": "merchantBangoCustomDataValue1",
    "merchantCustomData2": "merchantBangoCustomDataValue2",
    "merchantCustomData3": "merchantBangoCustomDataValue3"
  }
}

{
  "responseCode": "BAD_REQUEST",
  "responseMessage": "Invalid request"
}

{
  "responseCode": "UNAUTHORIZED",
  "responseMessage": "You have not provided adequate credentials to access this resource."
}

{
  "responseCode": "NOT_FOUND",
  "responseMessage": "Entitlement not found"
}

{
  "responseCode": "INVALID_STATE",
  "responseMessage": "Operation invalid for the current state of the entitlement."
}

{
  "responseCode": "TOO_MANY_REQUESTS",
  "responseMessage": "Request limit reached. Please try again later"
}

{
  "responseCode": "INTERNAL_ERROR",
  "responseMessage": "The server encountered an unexpected condition which prevented it from fulfilling the request"
}

{
  "responseCode": "SERVICE_UNAVAILABLE",
  "responseMessage": "The server is undergoing maintenance and is not available. Please, try again later"
}

Authorizations

Authorization

string

header

required

Basic authentication

Headers

X-RequestIdentifier

string

Request unique identifier. If present, this id will be used for idempotency.

Path Parameters

merchantEntitlementId

string<uuid>

required

Unique identifier used on activation.

Body

application/json

The entitlement terminate JSON.

terminatedDate

string<date-time>

required

Date when the entitlement was terminated.

Example:

"2019-10-14T15:34:49Z"

immediate

boolean

Determines if the termination is effective immediately. If nothing is passed, the request will default to TRUE. Immediate termination results in HARD ending of the entitlement:

TRUE
FALSE

reasonCategory

string

Code representing the entitlement terminate reason. This code can be any value, but we recommend you use one of the following codes:

"CUSTOMER_CANCELLED"
"REVOKED"
"CUSTOMER_CHANGED"
"ACTIVATION_ROLLBACK"

Example:

"ACTIVATION_ROLLBACK"

reasonCode

string

Code representing the entitlement terminate reason. This code can be any value, but we recommend you use one of the following codes:

"FRAUD": The user has not renewed the subscription
"ACCOUNT_TERMINATED": The user is no longer a customer
"SECURITY": For security reasons, access to this entitlement has been terminated
"OTHER": Other

Example:

"FRAUD"

reasonDescription

string

Description of the entitlement revoke reason

Example:

"Personal data stolen"

merchantExtensionData

object

financeData

object

Show child attributes

Response

Entitlement terminated successfully

responseCode

string

Example:

"OK"

responseMessage

string

Example:

"Success"

requestId

string

Bango unique identifier representing an entitlement.

Example:

"981a55a5-b3a4-46dc-9fac-a86227b26344"

bangoUserId

string

User unique identifier.

Example:

"1549053185"

sharedCustomerId

string<uuid>

Bango generated id shared between reseller and merchant for this customer (contact support for setup)

Example:

"414b3019-0c28-4d14-9c5f-6217b8bd1e3e"

productId

string

Entitlement product unique identifier. For example, "30_DAYS_MUSIC".

Example:

"30_DAYS_MUSIC"

offerId

string

The offer given to the user for the merchant service. For example, "FREE_FOR_6_MONTHS".

Example:

"FREE_FOR_6_MONTHS"

resellerId

string

Unique reseller identifier

Example:

"XYZ_RESELLER"

customerId

string

Unique identifier representing a specific customer of the reseller not anonymised. This value will only be sent by Bango if the Merchant and Reseller both approve the sharing of this data

status

enum<string>

Entitlement status. Possible values are:

"ACTIVE": The entitlement has been successfully activated
"CANCELLED": The entitlement has been cancelled.
"REVOKED": The entitlement has been revoked. This usually happens on fraud and user contract termination cases.
"SUSPENDED": The entitlement has been suspended.
"PENDING": The entitlement has been initiated, but the user has not yet finalized the activation process.
"FAILED": The entitlement failed
"ACTIVE-ENDING": The entitlement is ending at the end of the current period.

Available options:

REVOKED,

ACTIVE,

CANCELLED,

SUSPENDED,

PENDING,

FAILED,

ACTIVE-ENDING

dateCreated

string<date-time>

Date and time when the entitlement was created, in UTC ISO 8601 format (yyyy-MM-ddThh:mm:ssZ)

dateActivated

string<date-time>

Date and time when the entitlement was activated, in UTC ISO 8601 format (yyyy-MM-ddThh:mm:ssZ)

dateExpiry

string<date-time>

Entitlement expiry date in UTC ISO 8601 format. Null if no expiry (yyyy-MM-ddThh:mm:ssZ)

Example:

null

dateEnded

string<date-time>

Date and time when the entitlement ended due to termination, in UTC ISO 8601 format (yyyy-MM-ddThh:mm:ssZ)

dateSuspended

string<date-time>

Date and time when the entitlement was suspended, in UTC ISO 8601. Null if status is not Suspended. format (yyyy-MM-ddThh:mm:ssZ)

Example:

null

dateResumed

string<date-time>

Date and time when the entitlement was suspended, in UTC ISO 8601. Null if the entitlement hasn't ever been resumed before. Format (yyyy-MM-ddThh:mm:ssZ)

Example:

null

dateAutoSuspend

string<date-time>

Date and time when the entitlement will be automatically suspended at the request of the reseller, in UTC ISO 8601. Null if date is not set. Format (yyyy-MM-ddThh:mm:ssZ)

Example:

null

merchantExtensionData

object

Show child attributes

Example:

{
  "merchantCustomData1": "merchantCustomDataValue1",
  "merchantCustomData2": "merchantCustomDataValue2",
  "merchantCustomData3": "merchantCustomDataValue3"
}

extraInformation

object

Show child attributes

financeData

object

Show child attributes

merchantBangoExtensionData

object

Show child attributes

Example:

{
  "merchantCustomData1": "merchantBangoCustomDataValue1",
  "merchantCustomData2": "merchantBangoCustomDataValue2",
  "merchantCustomData3": "merchantBangoCustomDataValue3"
}

DVM APIs

Products

Offers

Consumer Offers

Entitlements

Notifications

Eligibility

Charge

Testing

Terminate an entitlement

Authorizations

Headers

Path Parameters

Body

Response