Create a new entitlement

curl --request POST \
  --url https://virtserver.swaggerhub.com/BangoProducts/Reseller-API/1.0.23/v1/entitlement \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerIdentifier": "4407123456789",
  "merchantAccountKey": "BANGO",
  "productKey": "BangoMusic",
  "notificationUrl": "https://www.example.com/notification/a25100b8-4e0c-4e37-b921-cac9cb1e930f"
}
'

{
  "entitlementId": "a25100b8-4e0c-4e37-b921-cac9cb1e930f",
  "customerIdentifier": "4407123456789",
  "sharedCustomerId": "414b3019-0c28-4d14-9c5f-6217b8bd1e3e",
  "productKey": "BangoMusic",
  "entitlementDisplayName": "30 days Bango music",
  "offerKey": null,
  "merchantAccountKey": "BANGO",
  "activationCode": null,
  "dateCreated": "2020-06-22T17:35:38.92Z",
  "dateActivated": "2020-06-22T17:35:59.90Z",
  "dateEnded": "0001-01-01T00:00:00Z",
  "dateExpiry": "0001-01-01T00:00:00Z",
  "dateAutoSuspend": null,
  "dateFailed": "0001-01-01T00:00:00Z",
  "dateSuspended": null,
  "dateResumed": null,
  "responseCode": "OK",
  "responseMessage": "Success",
  "status": "ACTIVE",
  "externalEntitlementId": "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63",
  "extensionData": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "parameters": null,
  "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": "Activation"
    }
  }
}

POST

https://virtserver.swaggerhub.com/BangoProducts/Reseller-API/1.0.23

entitlement

curl --request POST \
  --url https://virtserver.swaggerhub.com/BangoProducts/Reseller-API/1.0.23/v1/entitlement \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customerIdentifier": "4407123456789",
  "merchantAccountKey": "BANGO",
  "productKey": "BangoMusic",
  "notificationUrl": "https://www.example.com/notification/a25100b8-4e0c-4e37-b921-cac9cb1e930f"
}
'

{
  "entitlementId": "a25100b8-4e0c-4e37-b921-cac9cb1e930f",
  "customerIdentifier": "4407123456789",
  "sharedCustomerId": "414b3019-0c28-4d14-9c5f-6217b8bd1e3e",
  "productKey": "BangoMusic",
  "entitlementDisplayName": "30 days Bango music",
  "offerKey": null,
  "merchantAccountKey": "BANGO",
  "activationCode": null,
  "dateCreated": "2020-06-22T17:35:38.92Z",
  "dateActivated": "2020-06-22T17:35:59.90Z",
  "dateEnded": "0001-01-01T00:00:00Z",
  "dateExpiry": "0001-01-01T00:00:00Z",
  "dateAutoSuspend": null,
  "dateFailed": "0001-01-01T00:00:00Z",
  "dateSuspended": null,
  "dateResumed": null,
  "responseCode": "OK",
  "responseMessage": "Success",
  "status": "ACTIVE",
  "externalEntitlementId": "124130d2-2cbc-45a1-ab9b-dfa8b67a2e63",
  "extensionData": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  },
  "parameters": null,
  "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": "Activation"
    }
  }
}

Authorizations

Authorization

string

header

required

Basic authentication

Headers

X-RequestIdentifier

string

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

Body

application/json

The entitlement JSON you want to create

customerIdentifier

string

required

User unique identifier.

Example:

"4407123456789"

merchantAccountKey

string

required

Merchant unique identifier. For example, "BANGO".

Example:

"BANGO"

productKey

string

required

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

Example:

"BangoMusic"

notificationUrl

string<url>

required

The endpoint where all POST notifications will be sent after subscription creation. The body of the POST request will contain the entitlement information in https://developer.bango.com/resale/api-ref/notifications.

Example:

"https://www.example.com/notification/a25100b8-4e0c-4e37-b921-cac9cb1e930f"

entitlementDisplayName

string

Entitlement display name. For example, "30 days Bango music" (optional).

Example:

"30 days of Bango music"

offerKey

string

Entitlement offer. For example, "BUNDLE" (optional).

Example:

null

dateExpiry

string<date>

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

Example:

null

dateAutoSuspend

string<date>

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

Example:

null

externalEntitlementId

string

External identifier for the Entitlement from the Reseller.

Example:

"124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"

extensionData

object

Show child attributes

Example:

{
  "additionalCustomData1": "additionalCustomDataValue1",
  "additionalCustomData2": "additionalCustomDataValue2",
  "additionalCustomData3": "additionalCustomDataValue3"
}

extraInformation

object

Show child attributes

Response

Entitlement created and activated successfully.

entitlementId

string

required

Unique identifier representing a specific entitlement.

Example:

"a25100b8-4e0c-4e37-b921-cac9cb1e930f"

customerIdentifier

string

required

User unique identifier.

Example:

"4407123456789"

productKey

string

required

Entitlement product unique identifier. For example, "BangoMusic".

Example:

"BangoMusic"

offerKey

string

required

Entitlement offer. For example, "BUNDLE".

Example:

null

merchantAccountKey

string

required

Merchant unique identifier. For example, "BANGO".

Example:

"BANGO"

dateCreated

string<date-time>

required

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

dateActivated

string<date-time>

required

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

dateEnded

string<date-time>

required

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

Example:

"0001-01-01T00:00:00Z"

dateExpiry

string<date-time>

required

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

Example:

"0001-01-01T00:00:00Z"

responseCode

string

required

Example:

"OK"

responseMessage

string

required

Example:

"Success"

status

enum<string>

required

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:

ACTIVE,

CANCELLED,

REVOKED,

SUSPENDED,

PENDING,

FAILED,

ACTIVE-ENDING

Example:

"ACTIVE"

sharedCustomerId

string<uuid>

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

Example:

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

entitlementDisplayName

string

Entitlement display name. For example, "30 days Bango music".

Example:

"30 days Bango music"

activationCode

string

Code or token use for the entitlement activation.

Example:

null

dateAutoSuspend

string<date>

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

Example:

null

dateFailed

string<date-time>

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

Example:

"0001-01-01T00:00:00Z"

dateSuspended

string<date-time>

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

Example:

null

dateResumed

string<date-time>

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

Example:

null

externalEntitlementId

string

External identifier for the Entitlement from the Reseller.

Example:

"124130d2-2cbc-45a1-ab9b-dfa8b67a2e63"

extensionData

object

Accepts a dynamic list of key-value pairs to cover custom data needs

Show child attributes

parameters

object

Show child attributes

extraInformation

object

Show child attributes

financeData

object

Show child attributes

General

Reseller

Merchant

End of Life

Authorizations

Headers

Body

Response