Addon-item and charge-item prices are purchased with plan-item prices in subscriptions. You can automate this process by configuring certain addons and charges as “attached” to certain plans. This is done at the “item” level. In other words, addon- and charge-items can be attached to plan-items.
Once the attachment is defined, while creating or updating a subscription, the addon- or charge-item prices are selected automatically based on the plan-item price selected . Let’s look at the details:
Addons can be attached to plans as recommended
, mandatory
or optional
.
recommended
for a plan, the addon is suggested to be applied to subscriptions for the plan in Checkout and Self-Serve Portal. Alternatively, if you build your own payment pages or have a sales team, you can suggest recommended addons to your customers or salespeople on your website or CRM respectively mandatory
for a plan, the addon gets applied to subscriptions for the plan compulsorily, unless removed explicitly. If you do not pass an item price for a mandatory addon when including the plan in a subscription, an addon-item price is automatically applied as explained below. optional
neither marks it as recommended or mandatory but allows you a way to set a quantity
and billing_cycles
for the addon, for when it is applied to subscriptions with the plan. Once an addon has been attached as mandatory, the addon-item price to be applied to the plan-item price is selected based on the following rule: The addon-item price with the same currency as that of the plan-item price and the longest compatible period is selected.
Here's an example:
Consider a plan Standard Cloud Storage has an addon Extra Storage attached to it. Note that each of the two are items. Now consider that they have item prices with the following periods and currencies:
Item price for “Standard Cloud Storage” plan-item:
Item prices for “Extra Storage” addon-item:
For the plan-item price (Standard Cloud Storage, 3 years, AUD), the addon-item prices with matching currencies are the last 4 from the above list:
From among them, the last two have periods that are incompatible with the plan-item price period of 3 years. From the remaining 2 addon-item prices, the one with the longest period is of 18 months. So, “Extra Storage, 18 months, AUD” is selected for mandatory application to the plan item price.
Charges can also be attached to plans. When doing so, you specify the event at which the charge is to be applied to the subscription. For some events that can occur multiple times in a subscription lifetime, you can also set whether to apply the charge each time the event occurs or just once.
There may be multiple item prices for a given attached charge. The item price that matches the currency of the plan-item price is automatically selected for application.
Here’s an example:
Consider a plan Standard Cloud Storage has a charge named Implementation Fee attached to it. Now consider their item prices below, with the following periods and currencies:
Item price for “Standard Cloud Storage” plan-item:
Item prices for “Implementation Fee” charge-item:
From among the charge-item prices above, the one compatible with the plan-item price is “Implementation Fee, AUD” since it has the same currency as the plan-item price.
{
"created_at": 1594107081,
"id": "c9109b84-732a-4093-b53d-0b9f31ccc11c",
"item_id": "day-pass",
"object": "attached_item",
"parent_item_id": "basic",
"quantity": 1,
"resource_version": 1594107081871,
"status": "active",
"type": "mandatory",
"updated_at": 1594107081
}
ChargeBee.Models.AttachedItem
quantity
and billing_cycles
for the addon, for when it is applied to subscriptions with the plan.billing_cycles
while applying the addon to a subscription takes precedence over this attribute. This attribute, in turn, has a higher precedence than the value set for the addon-item price. active
or non-renewing
state. Also includes reactivations of canceled subscriptions.ContractTerminationwhen a contract term is terminated.OnDemandItem can be charged on demandCreates an attached addon or a charge item for a plan.
using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = AttachedItem.Create("basic") .ItemId("day-pass") .Type(TypeEnum.Mandatory) .Quantity(1) .Request(); AttachedItem attachedItem = result.AttachedItem;
using ChargeBee.Api; using ChargeBee.Models; using ChargeBee.Models.Enums; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = AttachedItem.Create("basic") .ItemId("ssl") .ChargeOnEvent(ChargeOnEventEnum.SubscriptionCreation) .ChargeOnce(true) .Request(); AttachedItem attachedItem = result.AttachedItem;
AttachedItem.Create(<item_id>)
quantity
and billing_cycles
for the addon, for when it is applied to subscriptions with the plan.billing_cycles
while applying the addon to a subscription takes precedence over this parameter. This parameter, in turn, has a higher precedence than the value set for the addon-item price. active
or non-renewing
state. Also includes reactivations of canceled subscriptions.ContractTerminationwhen a contract term is terminated.OnDemandItem can be charged on demandThe unique ID of the business entity for this attached_item
. This is applicable only when multiple business entities have been created for the site. When provided, the operation will read or write data associated with the specified business entity. If not provided, the resource will be created at the site level, and the business_entity_id
will not be included in the API response.
Note: An alternative way of passing this parameter is by using a custom HTTP header or query string parameter.
.Updates an attached addon or a charge item for a plan.
using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = AttachedItem.Update("85943f11-6014-4ab5-990d-60c86a9c2893") .ParentItemId("cb-demo") .Type(TypeEnum.Recommended) .Request(); AttachedItem attachedItem = result.AttachedItem;
using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = AttachedItem.Update("85943f11-6014-4ab5-990d-60c86a9c2893") .ParentItemId("cb-demo") .Type(TypeEnum.Recommended) .Request(); AttachedItem attachedItem = result.AttachedItem;
AttachedItem.Update(<attached_item_id>)
quantity
and billing_cycles
for the addon, for when it is applied to subscriptions with the plan.billing_cycles
while applying the addon to a subscription takes precedence over this parameter. This parameter, in turn, has a higher precedence than the value set for the addon-item price. active
or non-renewing
state. Also includes reactivations of canceled subscriptions.ContractTerminationwhen a contract term is terminated.OnDemandItem can be charged on demandRetrieves details of an attached addon or a charge item.
using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = AttachedItem.Retrieve("a0d63a3a-4bea-4621-b4c9-1bb7f833a603") .ParentItemId("cb-demo") .Request(); AttachedItem attachedItem = result.AttachedItem;
using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = AttachedItem.Retrieve("a0d63a3a-4bea-4621-b4c9-1bb7f833a603") .ParentItemId("cb-demo") .Request(); AttachedItem attachedItem = result.AttachedItem;
AttachedItem.Retrieve(<attached_item_id>)
Deletes an attached addon or a charge item.
using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = AttachedItem.Delete("bf0d81c1-eb45-4636-ad8e-5ab31099e325") .ParentItemId("no-trial") .Request(); AttachedItem attachedItem = result.AttachedItem;
using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = AttachedItem.Delete("bf0d81c1-eb45-4636-ad8e-5ab31099e325") .ParentItemId("no-trial") .Request(); AttachedItem attachedItem = result.AttachedItem;
AttachedItem.Delete(<attached_item_id>)
using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); ListResult result = AttachedItem.List("basic") .Limit(10) .Request(); foreach (var item in result.List){ AttachedItem attachedItem = item.AttachedItem; }
using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); ListResult result = AttachedItem.List("basic") .Limit(10) .Request(); foreach (var item in result.List){ AttachedItem attachedItem = item.AttachedItem; }
AttachedItem.List(<item_id>)