Skip to main content
Vindicia Knowledge Center

The BillingPlan object

The BillingPlan object

The BillingPlan object is the schedule and, optionally, pricing rules for a subscription; every subscription must have a BillingPlan assigned.

Attributes

BillingPlan

Name Type Description
object string Value is “BillingPlan”
id string A merchant-specified unique identifier. If not specified, this object can be identified by its vid.
vid string A Globally Unique Identifier (GUID) for this object. Assigned by CashBox.
created datetime The date and time the plan was created.
description string A Merchant-specified description of this offering.
status enum Merchants may define whether they want to declare a plan as available to offer. Values can be Active,Suspended
tax_classification string The tax classification or code to be used with any plan-level charges.
trial BillingPlanPeriod Optionally declares an initial trial period for this plan.
periods BillingPlanPeriod[] Defines the sequential billing periods in the plan, each with its own billing schedule and terms.
billing_notification_days integer Number of days prior to schedule billing at which CashBox will send email notification.
trial_end_notification_days integer For the trial period, this replaces billing_notification_days, indicating the # of days prior to end of a trial to send the trial end email.
skip_initial_billing_notification boolean Determines whether to send a billing notification for the initial period.
end_of_life datetime The date after which the plan should not be offered.
metadata hash A set of key/value pairs that you can attach to an object. Useful for storing additional information.
entitlements Entitlement[] Entitlements granted by active subscriptions on this plan.
billing_descriptor string Optional “soft descriptor” to send to the payment processor for transactions associated with a subscription using this billing plan.
times_to_run string Advanced setting (see programming guide)
entitlements_valid_for string Advanced setting (see programming guide)
repeat_every string Advanced setting (see programming guide)
season_set SeasonSet Season Set
days_before_season_to_bill integer Advanced setting (see programming guide)
days_entitled_before_season integer Advanced setting (see programming guide)
days_entitled_after_season integer Advanced setting (see programming guide)
entitled_off_season boolean Advanced setting (see programming guide)

BillingPlanPeriod

Name Type Description
object string Value is “BillingPlanPeriod”
type enum Unit of time a period describes. Values can be Day,Week,Month,Year
quantity integer  
cycles integer  
prices BillingPlanPrice[] A price for each defined currency for each period. Optional - Billing Plans do not require pricing (can be priced at the item/product level).

BillingPlanPrice

Name Type Description
object string Value is “BillingPlanPrice”
amount decimal price.
currency string ISO 4217 Currency Code of price.
price_list_name string Name of price list containing this price. This is free-form string of 255 characters or less
token_amount TokenAmount The number of tokens required to purchase (if token-priced)
  • cURL
  • Java
Example Object
{
    "object": "BillingPlan",
    "id": "plan_1234",
    "vid": "1d557e85e70a13140dcc9bd4fd18a02f63f09084",
    "created": "2016-05-27T14:42:08-07:00",
    "description": "Simple Monthly Billing Plan",
    "status": "Active",
    "periods": {
        "object": "List",
        "data": [
        {
        "object": "BillingPlanPeriod",
        "type": "Month",
        "quantity": 1,
        "cycles": 0,
        "prices": {
            "object": "List",
            "data": [
            {
            "object": "BillingPlanPrice",
            "amount": 0,
            "currency": "USD"
            }
            ],
        "total_count": 1
        }
    }
    ],
    "total_count": 1
    },
    "end_of_life": "2099-12-31T00:00:00-08:00",

    "metadata": {
        "CatalogID": "plan1234"
        },
    "entitlements": {
        "object": "List",
        "data": [
        {
            "object": "Entitlement",
            "id": "plan_1234",
            "description": "plan_1234"
        }
        ],
    "total_count": 1
    }
}
          
{
    "object": "BillingPlan",
    "id": "plan_1234",
    "vid": "1d557e85e70a13140dcc9bd4fd18a02f63f09084",
    "created": "2016-05-27T14:42:08-07:00",
    "description": "Simple Monthly Billing Plan",
    "status": "Active"
    "periods": {
        "object": "List",
        "data": [
        {
        "object": "BillingPlanPeriod",
        "type": "Month",
        "quantity": 1,
        "cycles": 0,
        "prices": {
            "object": "List",
            "data": [
            {
            "object": "BillingPlanPrice",
            "amount": 0,
            "currency": "USD"
            }
            ],
        "total_count": 1
        }
    }
    ],
    "total_count": 1
    },
    "end_of_life": "2099-12-31T00:00:00-08:00",

    "metadata": {
        "CatalogID": "plan1234"
        },
    "entitlements": {
        "object": "List",
        "data": [
        {
            "object": "Entitlement",
            "id": "plan_1234",
            "description": "plan_1234"
        }
        ],
    "total_count": 1
    }
}
          

For Users

Learn More
For Users

Cashbox Features

Learn More
Cashbox Features
Back to Top