Retrieve a subscription by external key

curl --request GET \
  --url https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription/externalKey/{externalKey} \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription/externalKey/{externalKey}', 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/externalKey/{externalKey}"

headers = {"Authorization": "Basic <encoded-value>"}

response = requests.get(url, 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": "NOT_FOUND",
  "responseMessage": "Subscription not found"
}

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

GET

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

subscription

externalKey

{externalKey}

Retrieve a subscription by external key

curl --request GET \
  --url https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription/externalKey/{externalKey} \
  --header 'Authorization: Basic <encoded-value>'

const options = {method: 'GET', headers: {Authorization: 'Basic <encoded-value>'}};

fetch('https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription/externalKey/{externalKey}', 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/externalKey/{externalKey}"

headers = {"Authorization": "Basic <encoded-value>"}

response = requests.get(url, 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": "NOT_FOUND",
  "responseMessage": "Subscription not found"
}

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

Path Parameters

externalKey

string

required

The unique custom identifier supplied in the externalKey property when creating the subscription 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"

Query Parameters

audit

enum<string>

default:NONE

FULL will return ...
MINIMAL will return only UPDATE audit events
NONE will return no audit events

Available options:

FULL,

MINIMAL,

NONE

Response

Subscription found

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

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"

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

Retrieve a subscription by external key

Authorizations

Path Parameters

Query Parameters

Response