CRUD Subscriptions

The following endpoints can be used to maintain a subscription for a tenant.

Create subscription

You can use the following endpoint within your custom pages in order to subscribe to a billing plan for the tenant. 

Summary

  • Endpoint: /api/v2/billing_subscribe
  • Method: POST
  • Required User Type: TA

Body

  • subscription_plan_id - subscription plan id
    • Required 
  • coupon - a coupon set up through Stripe
  • token - Stripe token generated from credit card information
    • Required only if the billing plan amount is greater than 0

Response

A successful response will return a plain text "Success".

Example

Request body

{
coupon: "XXXX",
subscription_plan_id: "xxxxxxxxxxxxx",
token: "xxxxxxxx"
}

Response Data

"Success"

 

Retrieve subscription

You can use the following endpoint within your custom pages in order to retrieve current billing plan for a tenant.

Summary

  • Endpoint: /api/v2/billing_current_plan
  • Method: GET
  • Required User Type: TA

Response

A successful response will return an object which contains account information and current subscription information.

  • account_info - an object containing account information
    • balance - Stripe balance object
    • card - an object including credit card information
      • last4 - last 4 digit for credit card
      • brand - brand of credit card
      • exp_month - month of expiration date
      • exp_year - year of expiration date
    • delinquent - Stripe delinquent object
    • upcoming_invoice - basic information about upcoming invoice
      • date - Billing date, in Epoch time format
      • number - Invoice number
      • paid - Whether payment was successfully collected for this invoice
      • period_end - End time of the invoice, in Epoch time format
      • period_start - Start time of the invoice, in Epoch time format
      • total - Total amount in your currency in the smallest currency unit (e.g. cent)
      • line_items - Array of individual line items that make up the invoice, in reverse chronological order.
        • amount - amount in your currency in the smallest currency unit (e.g. cent)
        • currency - Three-letter ISO currency code, in uppercase
        • period_end - End time of the line item, in Epoch time format
        • period_start - Start time of the line item, in Epoch time format
        • description - Description for the line item
  • cc_updated_at - last credit card update time, in Epoch time format
  • plan_updated_at - last billing plan update time, in Epoch time format
  • status - status for current subscription
    • Possible values:  "Trial", "Active", "Past Due", "Canceled", "Cancelling", "Unpaid"
  • subscribed_at - subscribe time, in Epoch format
  • subscription_current_period_end - current subscription period end time, in Epoch time format
  • subscription_current_period_start - current subscription period start time, in Epoch time format
  • subscription_id - subscription id
  • subscription_plan - an object about subscribed billing plan

Example

Request

/api/v2/billing_current_plan

Response Data

  • With subscription
{
account_info: {
balance: 0,
card: {last4: "1234", brand: "MasterCard", exp_month: 1, exp_year: 2020},
delinquent: false,
upcomming_invoice:{
date: 1598392227,
id: null,
line_items: [{period_start: 1598392227, currency: "USD", amount: 1000, description: "Plan description",…}],
number: "XXXXXXX-0001",
paid: false,
payment_attempt_ts: 1598395827,
period_end: 1598392227,
period_start: 1595713827,
total: 0,
}
},
cc_updated_at: 1574815494,
plan_updated_at: 1579906341,
status: "Active",
subscribed_at: 1541461851,
subscription_current_period_end: 1598392227,
subscription_current_period_start: 1595713827,
subscription_id: "sub_Dv94ck8zeow22Q",
subscription_plan:{
active: true,
amount: 1000,
currency: "usd",
id: "plan_Fp6thP7RxK8b3b",
interval: "month",
interval_count: 1,
metadata: {},
name: "Test plan",
nickname: "Test plan",
statement_descriptor: null,
tiers: null,
}
}
  •  Without subscription
{
account_info: null
cc_updated_at: null
plan_updated_at: null
status: "n/a"
subscribed_at: null
subscription_current_period_end: null
subscription_current_period_start: null
subscription_id: "n/a"
subscription_plan: null
}

Update subscription

You can use the following endpoint within your custom pages in order to change billing plans for a tenant.

Prerequisite

  • Subscribed to a billing plan

Summary

  • Endpoint: /api/v2/billing_update_plan
  • Method: POST
  • Required User Type: TA

Request

  • subscription_plan_id - subscription plan id
    • Required 
  • coupon -  a coupon set up through Stripe

Response

A successful response will return a plain text "Success".

Example

Request Body

{
coupon: "XXXX",
subscription_plan_id: "xxxxxxxxxxxxx"
}

Response Data

"Success"

 

Delete subscription

You can use the following endpoint within your custom pages in order to unsubscribe for a tenant.

Prerequisite

  • Subscribed to a billing plan

Summary

  • Endpoint: /api/v2/billing_unsubscribe
  • Endpoint: /api/v2/billing_unsubscribe_no_pass
    Method: POST
  • Required User Type: TA

Request

  • password - password for current login user
    • Only required by /api/v2/billing_unsubscribe endpoint

Response

A successful response will return a plain text "Success".

Example

Request Body (Only required by /api/v2/billing_unsubscribe endpoint)

{
password: "xxxxxxxxxxx"
}

Response Data

"Success"