Change a subscription's plan

curl --request PUT \
  --url https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription/{subscriptionId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchantAccountKey": "BANGO_ENTERTAINMENT"
}
'

const options = {
  method: 'PUT',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({merchantAccountKey: 'BANGO_ENTERTAINMENT'})
};

fetch('https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription/{subscriptionId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription/{subscriptionId}"

payload = { "merchantAccountKey": "BANGO_ENTERTAINMENT" }
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "responseCode": "OK",
  "responseMessage": "Success",
  "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "bangoUserId": "1234567890",
  "externalKey": "my-external-identifier",
  "entitlementStartDate": "2020-08-19",
  "merchantAccountKey": "BANGO_ENTERTAINMENT",
  "productName": "bango-music",
  "extensionData": {
    "myCustomField": "my-custom-value",
    "mySecondCustomField": "another-value"
  },
  "billingPeriod": "MONTHLY",
  "phaseType": "TRIAL",
  "priceList": "<string>",
  "planName": "bango-music-3-months-free",
  "state": "ACTIVE",
  "cancelledDate": "2023-12-25",
  "chargedThroughDate": "2023-12-25",
  "billingStartDate": "2023-12-25",
  "billingEndDate": "2023-12-25",
  "billCycleDayLocal": 1,
  "nextPayment": {
    "amount": 9.99,
    "currency": "USD",
    "date": "2023-12-25"
  },
  "lastPayment": {
    "amount": 9.99,
    "currency": "USD",
    "date": "2023-12-25"
  },
  "events": [
    {
      "eventId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "billingPeriod": "MONTHLY",
      "effectiveDate": "2023-12-25",
      "planName": "bango-music-3-months-free",
      "productName": "bango-music",
      "priceList": "<string>",
      "eventType": "START_BILLING",
      "isBlockedBilling": true,
      "isBlockedEntitlement": true,
      "serviceName": "<string>",
      "serviceStateName": "<string>",
      "phase": "<string>",
      "auditLogs": [
        {
          "changeType": "UPDATE",
          "changeDate": "2023-11-07T05:31:56Z",
          "objectType": "SUBSCRIPTION",
          "objectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "changedBy": "admin",
          "reasonCode": null,
          "comments": null,
          "userToken": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "history": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "updatedDate": "2023-11-07T05:31:56Z",
            "createdDate": "2023-11-07T05:31:56Z"
          }
        }
      ]
    }
  ],
  "priceOverrides": [
    {
      "planName": "bango-music-3-months-free",
      "phaseName": "free-trial",
      "phaseType": "TRIAL",
      "fixedPrice": 0,
      "recurringPrice": 0
    }
  ],
  "prices": [
    {
      "planName": "bango-music-3-months-free",
      "phaseName": "free-trial",
      "phaseType": "TRIAL",
      "fixedPrice": 0,
      "recurringPrice": 0
    }
  ],
  "auditLogs": [
    {
      "changeType": "UPDATE",
      "changeDate": "2023-11-07T05:31:56Z",
      "objectType": "SUBSCRIPTION",
      "objectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "changedBy": "admin",
      "reasonCode": null,
      "comments": null,
      "userToken": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "history": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "updatedDate": "2023-11-07T05:31:56Z",
        "createdDate": "2023-11-07T05:31:56Z"
      }
    }
  ]
}

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

{
  "responseCode": "UNAUTHORIZED",
  "responseMessage": "Invalid access credential"
}

{
  "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"
}

Change a subscription's plan

Use this endpoint to change a subscription’s plan immediately or at a later date, given the unique identifier allocated by Bango for the subscription. This endpoint returns the updated subscription record.

To identify the plan, specify both the plan name and the merchant account key for the provider of the product or service.

Specify the date on which the plan should change by including either the billingPolicy or requestedDate parameters.

PUT

https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0

subscription

{subscriptionId}

Change a subscription's plan

curl --request PUT \
  --url https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription/{subscriptionId} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "merchantAccountKey": "BANGO_ENTERTAINMENT"
}
'

const options = {
  method: 'PUT',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({merchantAccountKey: 'BANGO_ENTERTAINMENT'})
};

fetch('https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription/{subscriptionId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription/{subscriptionId}"

payload = { "merchantAccountKey": "BANGO_ENTERTAINMENT" }
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "responseCode": "OK",
  "responseMessage": "Success",
  "subscriptionId": "123e4567-e89b-12d3-a456-426614174000",
  "bangoUserId": "1234567890",
  "externalKey": "my-external-identifier",
  "entitlementStartDate": "2020-08-19",
  "merchantAccountKey": "BANGO_ENTERTAINMENT",
  "productName": "bango-music",
  "extensionData": {
    "myCustomField": "my-custom-value",
    "mySecondCustomField": "another-value"
  },
  "billingPeriod": "MONTHLY",
  "phaseType": "TRIAL",
  "priceList": "<string>",
  "planName": "bango-music-3-months-free",
  "state": "ACTIVE",
  "cancelledDate": "2023-12-25",
  "chargedThroughDate": "2023-12-25",
  "billingStartDate": "2023-12-25",
  "billingEndDate": "2023-12-25",
  "billCycleDayLocal": 1,
  "nextPayment": {
    "amount": 9.99,
    "currency": "USD",
    "date": "2023-12-25"
  },
  "lastPayment": {
    "amount": 9.99,
    "currency": "USD",
    "date": "2023-12-25"
  },
  "events": [
    {
      "eventId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "billingPeriod": "MONTHLY",
      "effectiveDate": "2023-12-25",
      "planName": "bango-music-3-months-free",
      "productName": "bango-music",
      "priceList": "<string>",
      "eventType": "START_BILLING",
      "isBlockedBilling": true,
      "isBlockedEntitlement": true,
      "serviceName": "<string>",
      "serviceStateName": "<string>",
      "phase": "<string>",
      "auditLogs": [
        {
          "changeType": "UPDATE",
          "changeDate": "2023-11-07T05:31:56Z",
          "objectType": "SUBSCRIPTION",
          "objectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "changedBy": "admin",
          "reasonCode": null,
          "comments": null,
          "userToken": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "history": {
            "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
            "updatedDate": "2023-11-07T05:31:56Z",
            "createdDate": "2023-11-07T05:31:56Z"
          }
        }
      ]
    }
  ],
  "priceOverrides": [
    {
      "planName": "bango-music-3-months-free",
      "phaseName": "free-trial",
      "phaseType": "TRIAL",
      "fixedPrice": 0,
      "recurringPrice": 0
    }
  ],
  "prices": [
    {
      "planName": "bango-music-3-months-free",
      "phaseName": "free-trial",
      "phaseType": "TRIAL",
      "fixedPrice": 0,
      "recurringPrice": 0
    }
  ],
  "auditLogs": [
    {
      "changeType": "UPDATE",
      "changeDate": "2023-11-07T05:31:56Z",
      "objectType": "SUBSCRIPTION",
      "objectId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "changedBy": "admin",
      "reasonCode": null,
      "comments": null,
      "userToken": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "history": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "updatedDate": "2023-11-07T05:31:56Z",
        "createdDate": "2023-11-07T05:31:56Z"
      }
    }
  ]
}

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

{
  "responseCode": "UNAUTHORIZED",
  "responseMessage": "Invalid access credential"
}

{
  "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

Base64 encoding of username:password as supplied by Bango Support

Headers

X-RequestIdentifier

string

An arbitrary, optional, globally unique identifier for the request. If present, this ID is used for idempotency.

Path Parameters

subscriptionId

string<uuid>

required

The unique identifier generated by Bango for a subscription. The unique identifier generated by Bango for a subscription. This is a globally unique, opaque string

Example:

"123e4567-e89b-12d3-a456-426614174000"

Body

application/json

Data for changing a subscription's plan.

merchantAccountKey

string

required

The unique identifier for the merchant supplying the product or service. Bango assigns these identifiers

Example:

"BANGO_ENTERTAINMENT"

productName

string

When attempting a productName update, a planName must also be specified. The product catalog defines these identifiers

Example:

"bango-music"

planName

string

The unique identifier for the plan detailing the prices and offer periods associated with the subscription. Bango use NCName type which means that the planName cannot contain several symbol characters like :, @, $, %, &, /, +, ,, ;, whitespace characters or different parenthesis.

Example:

"bango-music-3-months-free"

billingPolicy

enum<string>

When the change of plan becomes effective. (Include either this parameter or requestedDate - not both.)

Available options:

START_OF_TERM,

END_OF_TERM,

IMMEDIATE

requestedDate

string<date>

When the change of plan becomes effective. (Include either this parameter or billingPolicy - not both.)

extensionData

object

Arbitrary key-value pairs, where values are always strings. API consumers can use this to store custom data for the subscription.

Show child attributes

Example:

{
  "myCustomField": "my-custom-value",
  "mySecondCustomField": "another-value"
}

Response

Subscription found and updated

A subscription record in the Bango Platform

responseCode

enum<string>

required

Always 'OK'

Available options:

OK

responseMessage

string

required

Example:

"Success"

subscriptionId

string<uuid>

The unique identifier generated by Bango for a subscription. This is a globally unique, opaque string

Example:

"123e4567-e89b-12d3-a456-426614174000"

bangoUserId

string

The Bango user identifier. This is a globally unique, opaque string.

Example:

"1234567890"

externalKey

string

An optional unique identifier for the subscription, meaningful to the API consumer. This must be a globally unique, opaque string.

Use this identifier as an alternative to the subscriptionId assigned by Bango.

Example:

"my-external-identifier"

entitlementStartDate

string<date>

The YYYY-MM-DD UTC date on which the subscription entitlement starts

Example:

"2020-08-19"

merchantAccountKey

string

The unique identifier for the merchant supplying the product or service. Bango assigns these identifiers

Example:

"BANGO_ENTERTAINMENT"

productName

string

The unique identifier for the product or service the user is subscribing to. The product catalog defines these identifiers. The first character of the planName can't be a number.

Example:

"bango-music"

extensionData

object

Arbitrary key-value pairs, where values are always strings. API consumers can use this to store custom data for the subscription.

Show child attributes

Example:

{
  "myCustomField": "my-custom-value",
  "mySecondCustomField": "another-value"
}

billingPeriod

enum<string>

How frequently the user is billed. For the avoidance of doubt:

BIWEEKLY = every 2 weeks
BIMESTRIAL = every 2 months
BIANNUAL = every 6 months
BIENNIAL = every 2 years

Available options:

MONTHLY,

DAILY,

WEEKLY,

BIWEEKLY,

THIRTY_DAYS,

SIXTY_DAYS,

NINETY_DAYS,

BIMESTRIAL,

QUARTERLY,

TRIANNUAL,

BIANNUAL,

ANNUAL,

BIENNIAL,

NO_BILLING_PERIOD

phaseType

enum<string>

Available options:

TRIAL,

DISCOUNT,

FIXEDTERM,

EVERGREEN

priceList

string

planName

string

Example:

"bango-music-3-months-free"

state

enum<string>

The current state of a subscription.

A subscription starts in ACTIVE if it's created with entitlementStartDate set to today's date or a past date. It starts in PENDING if entitlementStartDate is set to a future date, and automatically transitions to ACTIVE on that date.

A subscription is CANCELLED when the user no longer has access to the product or service. (A subscription scheduled to be cancelled at a future date is still ACTIVE until that date, and until then it can be uncancelled.)

Available options:

ACTIVE,

PENDING,

CANCELLED

cancelledDate

string<date> | null

If not null, the effective YYYY-MM-DD UTC date of cancellation. Might be a date in the future. If null, the subscription has not been cancelled.

chargedThroughDate

string<date>

The YYYY-MM-DD UTC date up to which the subscription has been paid for.

billingStartDate

string<date>

The YYYY-MM-DD UTC date on which billing starts or started.

billingEndDate

string<date> | null

If not null, the YYYY-MM-DD UTC date on which billing ends or ended. If null, billing has not ended.

billCycleDayLocal

integer<int32>

Example:

1

nextPayment

object

Details of a single payment. For nextPayment, this is the next payment scheduled to occur. For lastPayment, this is the most recent successful payment.

Show child attributes

lastPayment

object

Details of a single payment. For nextPayment, this is the next payment scheduled to occur. For lastPayment, this is the most recent successful payment.

Show child attributes

events

object[]

Show child attributes

priceOverrides

object[]

Show child attributes

prices

object[]

Show child attributes

auditLogs

object[]

Show child attributes

API Reference

Concepts

Change a subscription's plan

Authorizations

Headers

Path Parameters

Body

Response