Create a subscription

curl --request POST \
  --url https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bangoUserId": "1234567890",
  "userCurrency": "USD",
  "merchantAccountKey": "BANGO_ENTERTAINMENT",
  "productName": "bango-music",
  "planName": "bango-music-3-months-free",
  "entitlementStartDate": "2020-08-19",
  "billingStartDate": "2020-08-19"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    bangoUserId: '1234567890',
    userCurrency: 'USD',
    merchantAccountKey: 'BANGO_ENTERTAINMENT',
    productName: 'bango-music',
    planName: 'bango-music-3-months-free',
    entitlementStartDate: '2020-08-19',
    billingStartDate: '2020-08-19'
  })
};

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

payload = {
    "bangoUserId": "1234567890",
    "userCurrency": "USD",
    "merchantAccountKey": "BANGO_ENTERTAINMENT",
    "productName": "bango-music",
    "planName": "bango-music-3-months-free",
    "entitlementStartDate": "2020-08-19",
    "billingStartDate": "2020-08-19"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(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": "ALREADY_EXISTS",
  "responseMessage": "A plan with the same name already exists"
}

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

Create a subscription

Use this endpoint to create a subscription for a user in the Bango Platform.

You must supply the user’s Bango User ID and currency in the request body, as well as the merchant account key for the provider of the product or service, the product name, and the plan name.

You must set the entitlementStartDate and the billingStartDate to valid dates.

The subscription is set to state ACTIVE if entitlementStartDate is set to today’s date, or set to a date in the past. If it is set to a date in the future, the state is PENDING and will change automatically to ACTIVE at the entitlementStartDate.

POST

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

subscription

Create a subscription

curl --request POST \
  --url https://virtserver.swaggerhub.com/BangoProducts/Subscriptions-API/1.4.0/subscription \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bangoUserId": "1234567890",
  "userCurrency": "USD",
  "merchantAccountKey": "BANGO_ENTERTAINMENT",
  "productName": "bango-music",
  "planName": "bango-music-3-months-free",
  "entitlementStartDate": "2020-08-19",
  "billingStartDate": "2020-08-19"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    bangoUserId: '1234567890',
    userCurrency: 'USD',
    merchantAccountKey: 'BANGO_ENTERTAINMENT',
    productName: 'bango-music',
    planName: 'bango-music-3-months-free',
    entitlementStartDate: '2020-08-19',
    billingStartDate: '2020-08-19'
  })
};

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

payload = {
    "bangoUserId": "1234567890",
    "userCurrency": "USD",
    "merchantAccountKey": "BANGO_ENTERTAINMENT",
    "productName": "bango-music",
    "planName": "bango-music-3-months-free",
    "entitlementStartDate": "2020-08-19",
    "billingStartDate": "2020-08-19"
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

response = requests.post(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": "ALREADY_EXISTS",
  "responseMessage": "A plan with the same name already exists"
}

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

Body

application/json

Data for initializing a subscription.

bangoUserId

string

required

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

Example:

"1234567890"

userCurrency

enum<string>

required

A three-character ISO 4217 currency code.

Available options:

AED,

AFN,

ALL,

AMD,

ANG,

AOA,

ARS,

AUD,

AWG,

AZN,

BAM,

BBD,

BDT,

BGN,

BHD,

BIF,

BMD,

BND,

BOB,

BRL,

BSD,

BTC,

BTN,

BWP,

BYR,

BZD,

CAD,

CDF,

CHF,

CLP,

CNY,

COP,

CRC,

CUC,

CUP,

CVE,

CZK,

DJF,

DKK,

DOP,

DZD,

EGP,

ERN,

ETB,

EUR,

FJD,

FKP,

GBP,

GEL,

GGP,

GHS,

GIP,

GMD,

GNF,

GTQ,

GYD,

HKD,

HNL,

HRK,

HTG,

HUF,

IDR,

ILS,

IMP,

INR,

IQD,

IRR,

ISK,

JEP,

JMD,

JOD,

JPY,

KES,

KGS,

KHR,

KMF,

KPW,

KRW,

KWD,

KYD,

KZT,

LAK,

LBP,

LKR,

LRD,

LSL,

LTL,

LVL,

LYD,

MAD,

MDL,

MGA,

MKD,

MMK,

MNT,

MOP,

MRO,

MUR,

MVR,

MWK,

MXN,

MYR,

MZN,

NAD,

NGN,

NIO,

NOK,

NPR,

NZD,

OMR,

PAB,

PEN,

PGK,

PHP,

PKR,

PLN,

PYG,

QAR,

RON,

RSD,

RUB,

RWF,

SAR,

SBD,

SCR,

SDG,

SEK,

SGD,

SHP,

SLL,

SOS,

SPL,

SRD,

STD,

SVC,

SYP,

SZL,

THB,

TJS,

TMT,

TND,

TOP,

TRY,

TTD,

TVD,

TWD,

TZS,

UAH,

UGX,

USD,

UYU,

UZS,

VEF,

VND,

VUV,

WST,

XAF,

XCD,

XDR,

XOF,

XPF,

YER,

ZAR,

ZMW,

ZWD

Example:

"USD"

merchantAccountKey

string

required

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

Example:

"BANGO_ENTERTAINMENT"

productName

string

required

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"

planName

string

required

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"

entitlementStartDate

string<date>

required

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

Set to today's date or a date in the past to start the subscription entitlement immediately (state becomes ACTIVE).

Set to a date in the future to signify a pending subscription: the state starts in state PENDING and will transition to ACTIVE on that date.

Example:

"2020-08-19"

billingStartDate

string<date>

required

The YYYY-MM-DD UTC date on which the first payment is made for the subscription.

Example:

"2020-08-19"

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"

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 created successfully

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

Create a subscription

Authorizations

Headers

Body

Response