List Attached Items

The number of resources to be returned.

Default 10

<p class="mb-2">Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">offset</code> to the value of <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">next_offset</code> obtained in the previous iteration of the API call.</p>

optional, string filter Filter attached items based on their id. **Supported operators :** is, is_not, starts_with, in, not_in **Example →** *id\[is\] = "bec0c324-adb6-44d3-ad4f-694f449be97c"*

<dfn class="text-muted"><p class="mb-2">optional, string filter</p></dfn> <p class="mb-2">Filter attached items based on the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">item_id</code> of the item being attached. <strong class="font-semibold">Supported operators :</strong> is, is_not, starts_with, in, not_in</p> <p class="mb-2"><strong class="font-semibold">Example →</strong> <em class="italic">item_id[is] = &quot;basic&quot;</em></p>

<dfn class="text-muted"><p class="mb-2">optional, enumerated string filter</p></dfn> <p class="mb-2">Filter attached items based on the <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">type</code> of attached item. Possible values are : <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">recommended</code> , <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">mandatory</code> , <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">optional</code>. Possible values are : recommended, mandatory, optional.</p> <p class="mb-2"><strong class="font-semibold">Supported operators :</strong> is, is_not, in, not_in</p> <p class="mb-2"><strong class="font-semibold">Example →</strong> <em class="italic">type[is] = &quot;mandatory&quot;</em></p>

* `recommended` - The addon is recommended to go with the plan-item when using <a href="https://www.chargebee.com/docs/2.0/configure-inapp.html#fundamental-settings_recommending-addons-in-checkout" target="_blank">Checkout</a> or <a href="https://www.chargebee.com/docs/2.0/inapp-self-serve-portal.html#allow-change-subscription" target="_blank">Portal</a>. * `mandatory` - The addon is attached automatically to the subscription for the plan-item unless <a href="./subscriptions?prod_cat_ver=2">explicitly removed</a> via API. * `optional` - The addon is neither mandatory, nor recommended. This allows you to attach an addon so you can specify a <code>quantity</code> and <code>billing_cycles</code> for the addon, for when it is applied to subscriptions with the plan.

One ofrecommendedmandatoryoptional

* `recommended` - The addon is recommended to go with the plan-item when using <a href="https://www.chargebee.com/docs/2.0/configure-inapp.html#fundamental-settings_recommending-addons-in-checkout" target="_blank">Checkout</a> or <a href="https://www.chargebee.com/docs/2.0/inapp-self-serve-portal.html#allow-change-subscription" target="_blank">Portal</a>. * `mandatory` - The addon is attached automatically to the subscription for the plan-item unless <a href="./subscriptions?prod_cat_ver=2">explicitly removed</a> via API. * `optional` - The addon is neither mandatory, nor recommended. This allows you to attach an addon so you can specify a <code>quantity</code> and <code>billing_cycles</code> for the addon, for when it is applied to subscriptions with the plan.

One ofrecommendedmandatoryoptional

* `recommended` - The addon is recommended to go with the plan-item when using <a href="https://www.chargebee.com/docs/2.0/configure-inapp.html#fundamental-settings_recommending-addons-in-checkout" target="_blank">Checkout</a> or <a href="https://www.chargebee.com/docs/2.0/inapp-self-serve-portal.html#allow-change-subscription" target="_blank">Portal</a>. * `mandatory` - The addon is attached automatically to the subscription for the plan-item unless <a href="./subscriptions?prod_cat_ver=2">explicitly removed</a> via API. * `optional` - The addon is neither mandatory, nor recommended. This allows you to attach an addon so you can specify a <code>quantity</code> and <code>billing_cycles</code> for the addon, for when it is applied to subscriptions with the plan.

One ofrecommendedmandatoryoptional

* `recommended` - The addon is recommended to go with the plan-item when using <a href="https://www.chargebee.com/docs/2.0/configure-inapp.html#fundamental-settings_recommending-addons-in-checkout" target="_blank">Checkout</a> or <a href="https://www.chargebee.com/docs/2.0/inapp-self-serve-portal.html#allow-change-subscription" target="_blank">Portal</a>. * `mandatory` - The addon is attached automatically to the subscription for the plan-item unless <a href="./subscriptions?prod_cat_ver=2">explicitly removed</a> via API. * `optional` - The addon is neither mandatory, nor recommended. This allows you to attach an addon so you can specify a <code>quantity</code> and <code>billing_cycles</code> for the addon, for when it is applied to subscriptions with the plan.

One ofrecommendedmandatoryoptional

<dfn class="text-muted"><p class="mb-2">optional, enumerated string filter</p></dfn> <p class="mb-2">To filter based on the type of of the attached item. Possible values are : <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">addon</code> , <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">charge</code>. Possible values are : plan, addon, charge.</p> <p class="mb-2"><strong class="font-semibold">Supported operators :</strong> is, is_not, in, not_in</p> <p class="mb-2"><strong class="font-semibold">Example →</strong> <em class="italic">item_type[is_not] = &quot;plan&quot;</em></p>

\* \`plan\` - An essential component of a subscription. Every subscription has exactly one plan. It has a recurring charge and its period defines the billing period of the subscription. \* \`addon\` - A recurring component that can be added to a subscription in addition to its plan. \* \`charge\` - A non-recurring component that can be added to a subscription in addition to its plan. An charge can also be applied to a customer [directly](./invoices?prod_cat_ver=2#create_invoice_for_a_charge-item) without being applied to a subscription.

One ofplanaddoncharge

\* \`plan\` - An essential component of a subscription. Every subscription has exactly one plan. It has a recurring charge and its period defines the billing period of the subscription. \* \`addon\` - A recurring component that can be added to a subscription in addition to its plan. \* \`charge\` - A non-recurring component that can be added to a subscription in addition to its plan. An charge can also be applied to a customer [directly](./invoices?prod_cat_ver=2#create_invoice_for_a_charge-item) without being applied to a subscription.

One ofplanaddoncharge

\* \`plan\` - An essential component of a subscription. Every subscription has exactly one plan. It has a recurring charge and its period defines the billing period of the subscription. \* \`addon\` - A recurring component that can be added to a subscription in addition to its plan. \* \`charge\` - A non-recurring component that can be added to a subscription in addition to its plan. An charge can also be applied to a customer [directly](./invoices?prod_cat_ver=2#create_invoice_for_a_charge-item) without being applied to a subscription.

One ofplanaddoncharge

\* \`plan\` - An essential component of a subscription. Every subscription has exactly one plan. It has a recurring charge and its period defines the billing period of the subscription. \* \`addon\` - A recurring component that can be added to a subscription in addition to its plan. \* \`charge\` - A non-recurring component that can be added to a subscription in addition to its plan. An charge can also be applied to a customer [directly](./invoices?prod_cat_ver=2#create_invoice_for_a_charge-item) without being applied to a subscription.

One ofplanaddoncharge

optional, enumerated string filter Indicates when the item is charged. This attribute only applies to charge-items. Possible values are : subscription_creation, subscription_trial_start, plan_activation, subscription_activation, contract_termination, on_demand. **Supported operators :** is, is_not, in, not_in **Example →** *charge_on_event\[is\] = "subscription_creation"*

* `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 <code>active</code> or <code>non-renewing</code> state. Also includes reactivations of canceled subscriptions. * `contract_termination` - when a contract term is <a href="./subscriptions?prod_cat_ver=2#cancel_subscription_for_items_contract_term_cancel_option">terminated</a>. * `on_demand` - Item can be charged on demand

One ofsubscription_creationsubscription_trial_startplan_activationsubscription_activationcontract_terminationon_demand

* `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 <code>active</code> or <code>non-renewing</code> state. Also includes reactivations of canceled subscriptions. * `contract_termination` - when a contract term is <a href="./subscriptions?prod_cat_ver=2#cancel_subscription_for_items_contract_term_cancel_option">terminated</a>. * `on_demand` - Item can be charged on demand

One ofsubscription_creationsubscription_trial_startplan_activationsubscription_activationcontract_terminationon_demand

* `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 <code>active</code> or <code>non-renewing</code> state. Also includes reactivations of canceled subscriptions. * `contract_termination` - when a contract term is <a href="./subscriptions?prod_cat_ver=2#cancel_subscription_for_items_contract_term_cancel_option">terminated</a>. * `on_demand` - Item can be charged on demand

One ofsubscription_creationsubscription_trial_startplan_activationsubscription_activationcontract_terminationon_demand

* `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 <code>active</code> or <code>non-renewing</code> state. Also includes reactivations of canceled subscriptions. * `contract_termination` - when a contract term is <a href="./subscriptions?prod_cat_ver=2#cancel_subscription_for_items_contract_term_cancel_option">terminated</a>. * `on_demand` - Item can be charged on demand

One ofsubscription_creationsubscription_trial_startplan_activationsubscription_activationcontract_terminationon_demand

optional, timestamp(UTC) in seconds filter Filter attached items based on when the attached items were last updated. **Supported operators :** after, before, on, between **Example →** *updated_at\[after\] = "1243545465"*

The device from which the customer has made the request

The email address of your customer/user. Use this when the email address has only ASCII characters.

The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.

The IP address of the customer where the request originated

If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.

<div class="api-description"><p class="mb-2">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 &quot;attached&quot; to certain plans. This is done at the &quot;item&quot; level. In other words, addon- and charge-items can be attached to plan-items.</p><p class="mb-2">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&#x27;s look at the details:</p><h3>Addons</h3><p class="mb-2">Addons can be attached to plans as <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">recommended</code>, <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">mandatory</code> or <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">optional</code>.</p><ul class="list-disc list-outside ml-6 my-4 space-y-2"> <li class="text-base leading-relaxed">When an addon is attached as <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">recommended</code> for a plan, the addon is suggested to be applied to subscriptions for the plan in <a href="https://www.chargebee.com/docs/2.0/configure-inapp.html#fundamental-settings_recommending-addons-in-checkout" target="_blank">Checkout</a> and <a href="https://www.chargebee.com/docs/2.0/inapp-self-serve-portal.html#allow-change-subscription" target="_blank">Self-Serve Portal</a>. 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</li> <li class="text-base leading-relaxed">When an addon is attached as <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">mandatory</code> for a plan, the addon gets applied to subscriptions for the plan compulsorily, unless <a href="/docs/api/subscriptions">removed explicitly</a>. 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.</li> <li class="text-base leading-relaxed">Attaching an addon as <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">optional</code> neither marks it as recommended or mandatory but allows you a way to set a <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">quantity</code> and <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">billing_cycles</code> for the addon, for when it is applied to subscriptions with the plan.</li> </ul><h2>How auto-selection of the addon-item price works</h2><p class="mb-2">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.</p><p class="mb-2">Here&#x27;s an example:</p><p class="mb-2">Consider a plan <strong class="font-semibold">Standard Cloud Storage</strong> has an addon <strong class="font-semibold">Extra Storage</strong> attached to it. Note that each of the two are items. Now consider that they have item prices with the following periods and currencies:</p><p class="mb-2"><strong class="font-semibold">Item price for &quot;Standard Cloud Storage&quot; plan-item:</strong></p><ul class="list-disc list-outside ml-6 my-4 space-y-2"> <li class="text-base leading-relaxed">Standard Cloud Storage, 3 years, AUD.</li> </ul><p class="mb-2"><strong class="font-semibold">Item prices for &quot;Extra Storage&quot; addon-item:</strong></p><ul class="list-disc list-outside ml-6 my-4 space-y-2"> <li class="text-base leading-relaxed">Extra Storage, 1 year, EUR.</li> <li class="text-base leading-relaxed">Extra Storage, 1 year, USD.</li> <li class="text-base leading-relaxed">Extra Storage, 1 year, AUD.</li> <li class="text-base leading-relaxed">Extra Storage, 18 months, AUD.</li> <li class="text-base leading-relaxed">Extra Storage, 2 years, AUD.</li> <li class="text-base leading-relaxed">Extra Storage, 30 months, AUD.</li> </ul><p class="mb-2">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:</p><ul class="list-disc list-outside ml-6 my-4 space-y-2"> <li class="text-base leading-relaxed">Extra Storage, 1 year, AUD.</li> <li class="text-base leading-relaxed">Extra Storage, 18 months, AUD.</li> <li class="text-base leading-relaxed">Extra Storage, 2 years, AUD.</li> <li class="text-base leading-relaxed">Extra Storage, 30 months, AUD.</li> </ul><p class="mb-2">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, &quot;Extra Storage, 18 months, AUD&quot; is selected for mandatory application to the plan item price.</p><h3>Charges</h3><p class="mb-2">Charges can also be attached to plans. When doing so, you specify <a href="/docs/api/attached_items/attached_item-object#charge_on_event">the event</a> 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.</p><p class="mb-2">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.</p><p class="mb-2">Here&#x27;s an example:</p><p class="mb-2">Consider a plan <strong class="font-semibold">Standard Cloud Storage</strong> has a charge named <strong class="font-semibold">Implementation Fee</strong> attached to it. Now consider their item prices below, with the following periods and currencies:</p><p class="mb-2"><strong class="font-semibold">Item price for &quot;Standard Cloud Storage&quot; plan-item:</strong></p><ul class="list-disc list-outside ml-6 my-4 space-y-2"> <li class="text-base leading-relaxed">Standard Cloud Storage, 3 years, AUD.</li> </ul><p class="mb-2"><strong class="font-semibold">Item prices for &quot;Implementation Fee&quot; charge-item:</strong></p><ul class="list-disc list-outside ml-6 my-4 space-y-2"> <li class="text-base leading-relaxed">Implementation Fee, USD.</li> <li class="text-base leading-relaxed">Implementation Fee, AUD.</li> <li class="text-base leading-relaxed">Implementation Fee, EUR.</li> </ul><p class="mb-2">From among the charge-item prices above, the one compatible with the plan-item price is &quot;Implementation Fee, AUD&quot; since it has the same currency as the plan-item price.</p></div>

<p class="mb-2">This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter <code class="bg-gray-100 text-gray-800 font-medium border border-gray-300 rounded px-1.5 py-0.5 mx-1 text-sm font-mono whitespace-nowrap">offset</code>.</p>