Introducing the Better Auth Chargebee plugin: Use it to handle subscriptions, billing, and auth seamlessly.
Chargebeechargebee API

Create an attached item

Idempotency Supported

Creates an attached addon or a charge item for a plan.

Prerequisites & Constraints

  • item_id must belong to the same item family as item-id.
  • item_id must not already be attached to item-id.

Sample Request

attach a mandatory addon item
attach a charge item

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/items/{item-id}/attached_items

Input Parameters

item_id
required, string, max chars=100

The id of the addon or charge that is being attached to the plan-item.

Constraints
  • item_id must reference an existing item.
  • Cannot attach an item of type plan to an item
type
optional, enumerated string

The type of attachment for the addon. Only applicable for addon-items and is a required parameter as well for addon-items.

Constraints
  • type is required when item_id references an addon item.
  • type can be provided only when item_id references an addon item.
Enum Values
recommended

The addon is recommended to go with the plan-item when using Checkout or Portal .

mandatory

The addon is attached automatically to the subscription for the plan-item unless explicitly removed 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.

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 to be enabled for the site.

The value set explicitly for 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 .

Prerequisite
  • Addon billing cycles must be enabled for your site to set billing_cycles.
Constraint
  • billing_cycles can be provided only when item_id references an addon item. Defers to attached_item_billing_cycles_requires_feature when the addon-billing-cycles feature is off.
quantity
optional, integer, min=1

The default quantity of the addon to be attached when the quantity is not specified while creating /updating 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 is enabled.

Constraints
  • Multi-decimal pricing must be enabled for your site to set quantity_in_decimal.
  • quantity_in_decimal cannot be blank.
charge_on_event
optional, enumerated string

Indicates when the item is charged. This parameter only applies to charge-items.

Constraints
  • charge_on_event is required when item_id references a charge item.
  • charge_on_event can be provided only when item_id references a charge item.
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 .

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 parameter only applies to charge-items.

Required if
  • charge_once is required when item_id references a charge item with charge_on_event set to an event other than on_demand.
Constraint
  • charge_once can be provided only when item_id references a charge item.
business_entity_id
optional, string, max chars=50

The 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.

Constraint
  • When multiple business entities are active for Product Catalog, business_entity_id must reference a business entity accessible to your API key.

Returns

attached_item
Attached item object
Resource object representing attached_item