# Attached items

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


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[](#addons)

Addons can be attached to plans as `recommended`, `mandatory` or `optional`.

-   When an addon is attached as `recommended` for a plan, the addon is suggested to be applied to subscriptions for the plan in [Checkout](https://www.chargebee.com/docs/2.0/configure-inapp.html#fundamental-settings_recommending-addons-in-checkout) and [Self-Serve Portal](https://www.chargebee.com/docs/2.0/inapp-self-serve-portal.html#allow-change-subscription). 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
-   When an addon is attached as `mandatory` for a plan, the addon gets applied to subscriptions for the plan compulsorily, unless [removed explicitly](/docs/api/subscriptions). 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.
-   Attaching an addon as `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.

## How auto-selection of the addon-item price works[](#how-auto-selection-of-the-addon-item-price-works)

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:**

-   Standard Cloud Storage, 3 years, AUD.

**Item prices for "Extra Storage" addon-item:**

-   Extra Storage, 1 year, EUR.
-   Extra Storage, 1 year, USD.
-   Extra Storage, 1 year, AUD.
-   Extra Storage, 18 months, AUD.
-   Extra Storage, 2 years, AUD.
-   Extra Storage, 30 months, AUD.

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:

-   Extra Storage, 1 year, AUD.
-   Extra Storage, 18 months, AUD.
-   Extra Storage, 2 years, AUD.
-   Extra Storage, 30 months, AUD.

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[](#charges)

Charges can also be attached to plans. When doing so, you specify [the event](/docs/api/attached_items/attached_item-object#charge_on_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:**

-   Standard Cloud Storage, 3 years, AUD.

**Item prices for "Implementation Fee" charge-item:**

-   Implementation Fee, USD.
-   Implementation Fee, AUD.
-   Implementation Fee, EUR.

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.

## Sample Attached item

```json
{
  "created_at": 1594107090,
  "id": "85943f11-6014-4ab5-990d-60c86a9c2893",
  "item_id": "day-pass",
  "object": "attached_item",
  "parent_item_id": "cb-demo",
  "quantity": 1,
  "resource_version": 1594107092592,
  "status": "active",
  "type": "recommended",
  "updated_at": 1594107092
}
```

## Attached items attributes

## Input Parameters

- `id` (required, string, max chars=100)
  The unique id for the attached item. Set to a random, immutable value automatically when the attached item is created.

- `parent_item_id` (required, string, max chars=100)
  The `id` of the plan-item to which the item is attached.

- `item_id` (required, string, max chars=100)
  The id of the item being attached.

- `type` (required, enumerated string)
  The type of attachment for the addon. Only applicable for addon-items.
  Possible enum values:
    - `recommended`
      The addon is recommended to go with the plan-item when using [Checkout](https://www.chargebee.com/docs/2.0/configure-inapp.html#fundamental-settings_recommending-addons-in-checkout) or [Portal](https://www.chargebee.com/docs/2.0/inapp-self-serve-portal.html#allow-change-subscription) .
    - `mandatory`
      The addon is attached automatically to the subscription for the plan-item unless [explicitly removed](/docs/api/subscriptions) via API.
    - `optional`
      The addon is neither mandatory, nor recommended. This allows you to attach an addon so you can specify a `quantity` and `billing_cycles` for the addon, for when it is applied to subscriptions with the plan.

- `status` (optional, enumerated string)
  The item state.
  Possible enum values:
    - `active`
      New subscriptions can be created with the item.
    - `archived`
      No new subscriptions allowed for the item.
    - `deleted`
      No subscriptions allowed for the item.

- `quantity` (optional, integer, min=1)
  The default quantity of the addon to be attached when the quantity is not specified while [creating](/docs/api/subscriptions/create-subscription-for-items) /[updating](/docs/api/subscriptions/update-subscription-for-items) the subscription.

- `quantity_in_decimal` (optional, string, max chars=33)
  The decimal representation of the quantity of the addon. Returned for quantity-based addons when [multi-decimal pricing](/docs/api/getting-started) is enabled.

- `billing_cycles` (optional, integer, min=1)
  The number of subscription billing cycles for which this item is attached when applied to a subscription. Applicable only for items of type addon. Requires [addon billing cycles](https://www.chargebee.com/docs/2.0/addons-billingcycle.html) to be enabled for the site.
  
  The value set explicitly for `billing_cycles` while [applying the addon to a subscription](/docs/api/subscriptions/subscription-object#subscription_items) takes precedence over this attribute. This attribute, in turn, has a higher precedence than [the value set for the addon-item price](/docs/api/item_prices) .

- `charge_on_event` (optional, enumerated string)
  Indicates when the item is charged. This attribute only applies to charge-items.
  Possible enum values:
    - `subscription_creation`
      the time of creation of the subscription.
    - `subscription_trial_start`
      the time when the trial period of the subscription begins.
    - `plan_activation`
      same as subscription activation, but also includes the case when the plan-item of the subscription is changed.
    - `subscription_activation`
      the moment a subscription enters an `active` or `non-renewing` state. Also includes reactivations of canceled subscriptions.
    - `contract_termination`
      when a contract term is [terminated](/docs/api/subscriptions/cancel-subscription-for-items#contract_term_cancel_option) .
    - `on_demand`
      Item can be charged on demand

- `charge_once` (optional, boolean)
  Indicates if the charge-item is to be charged only once or each time the `charge_on_event` occurs. This attribute only applies to charge-items.

- `created_at` (required, timestamp(UTC) in seconds)
  The time at which this attached item was created.

- `resource_version` (optional, long)
  Version number of this resource. The `resource_version` is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

- `updated_at` (optional, timestamp(UTC) in seconds)
  The time at which this attached item was last updated.

- `channel` (optional, enumerated string)
  The subscription channel this object originated from and is maintained in.
  Possible enum values:
    - `web`
      The object was created (and is maintained) for the web channel directly in Chargebee via API or UI.
    - `app_store`
      The object data is synchronized with data from [in-app subscription(s)](/docs/api/in_app_subscriptions) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.
    - `play_store`
      The object data is synchronized with data from [in-app subscription(s)](/docs/api/in_app_subscriptions) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.

- `business_entity_id` (optional, string, max chars=50)
  The unique ID of the [business entity](/docs/api/getting-started) of this subscription. This is applicable only when multiple business entities have been created for the site. The value of this attribute indicates that the resource is specific to the given business entity.

- `deleted` (required, boolean)
  Indicates whether the attached item has been deleted or not.