# Create an attached item

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


[Idempotency Supported](/docs/api/idempotency)

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

## Sample Request

### attach a mandatory addon item

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/items/basic/attached_items \
     -u {site_api_key}:\
     -d item_id="day-pass" \
     -d type="MANDATORY" \
     -d quantity=1
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = AttachedItem.Create("basic")
		.ItemId("day-pass")
		.Type(AttachedItem.TypeEnum.Mandatory)
		.Quantity(1)
		.Request();

AttachedItem attachedItem = result.AttachedItem;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    attacheditemAction "github.com/chargebee/chargebee-go/v3/actions/attacheditem"
    "github.com/chargebee/chargebee-go/v3/models/attacheditem"
    attachedItemEnum "github.com/chargebee/chargebee-go/v3/models/attacheditem/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := attacheditemAction.Create("basic", &attacheditem.CreateRequestParams{
        ItemId : "day-pass",
        Type : attachedItemEnum.TypeMandatory,
        Quantity : chargebee.Int32(1),
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        AttachedItem := res.AttachedItem
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.AttachedItemCreateRequest{
    ItemId : "day-pass",
    Type : chargebee.AttachedItemTypeMandatory,
    Quantity : chargebee.Int32(1),
}
  res, err := client.AttachedItem.Create("basic", req)
      if err != nil {
        fmt.Println(err)
    } else {
        AttachedItem := res.AttachedItem
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = AttachedItem.create("basic")
            .itemId("day-pass")
            .type(AttachedItem.Type.MANDATORY)
            .quantity(1)
            .request();

        AttachedItem attachedItem = result.attachedItem();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.attachedItem.AttachedItem;
import com.chargebee.v4.models.attachedItem.params.AttachedItemCreateParams;
import com.chargebee.v4.models.attachedItem.responses.AttachedItemCreateResponse;

public class AttachedItemCreate {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        AttachedItemCreateParams params = AttachedItemCreateParams.builder()
            .itemId("day-pass")
            .type(AttachedItemCreateParams.Type.MANDATORY)
            .quantity(1)
            .build();

        AttachedItemCreateResponse response = client
            .attachedItems()
            .create("basic", params);

        AttachedItem attachedItem = response.getAttachedItem();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.attachedItem.create("basic", {
        item_id: "day-pass",
        type: "mandatory",
        quantity: 1
    });

    console.log(result);
    const attachedItem = result.attached_item;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->attachedItem()->create("basic", [
    "item_id" => "day-pass",
    "type" => "mandatory",
    "quantity" => 1
]);
$attachedItem = $result->attached_item;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.AttachedItem.create("basic",
    cb_client.AttachedItem.CreateParams(
        item_id="day-pass",
        type=chargebee.AttachedItem.Type.MANDATORY,
        quantity=1
    )
)
attached_item = response.attached_item
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::AttachedItem.create("basic",{
  :item_id => "day-pass",
  :type => "MANDATORY",
  :quantity => 1
})

attached_item = result.attached_item
```

### attach a charge item

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/items/basic/attached_items \
     -u {site_api_key}:\
     -d item_id="ssl" \
     -d charge_on_event="SUBSCRIPTION_CREATION" \
     -d charge_once="true"
```

#### .NET

```dotnet
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;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    attacheditemAction "github.com/chargebee/chargebee-go/v3/actions/attacheditem"
    "github.com/chargebee/chargebee-go/v3/models/attacheditem"
    enum "github.com/chargebee/chargebee-go/v3/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := attacheditemAction.Create("basic", &attacheditem.CreateRequestParams{
        ItemId : "ssl",
        ChargeOnEvent : enum.ChargeOnEventSubscriptionCreation,
        ChargeOnce : chargebee.Bool(true),
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        AttachedItem := res.AttachedItem
    }
}
```

#### Go

```go
package main

import (
  "fmt"
  "github.com/chargebee/chargebee-go/v4"
)

func main() {
  config := &chargebee.ClientConfig{
    SiteName: "{site}",
    ApiKey: "{site_api_key}",
  }    
  client := chargebee.NewClient(config)
  req := &chargebee.AttachedItemCreateRequest{
    ItemId : "ssl",
    ChargeOnEvent : chargebee.ChargeOnEventSubscriptionCreation,
    ChargeOnce : chargebee.Bool(true),
}
  res, err := client.AttachedItem.Create("basic", req)
      if err != nil {
        fmt.Println(err)
    } else {
        AttachedItem := res.AttachedItem
    }
}
```

#### Java

```java
import com.chargebee.*;
import com.chargebee.ListResult;
import com.chargebee.models.*;
import com.chargebee.models.enums.*;
import java.io.IOException;

public class Sample {

    public static void main(String args[]) throws IOException, Exception {
        Environment.configure("{site}", "{site_api_key}");
        Result result = AttachedItem.create("basic")
            .itemId("ssl")
            .chargeOnEvent(ChargeOnEvent.SUBSCRIPTION_CREATION)
            .chargeOnce(true)
            .request();

        AttachedItem attachedItem = result.attachedItem();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.attachedItem.AttachedItem;
import com.chargebee.v4.models.attachedItem.params.AttachedItemCreateParams;
import com.chargebee.v4.models.attachedItem.responses.AttachedItemCreateResponse;

public class AttachedItemCreate {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        AttachedItemCreateParams params = AttachedItemCreateParams.builder()
            .itemId("ssl")
            .chargeOnEvent(AttachedItemCreateParams.ChargeOnEvent.SUBSCRIPTION_CREATION)
            .chargeOnce(true)
            .build();

        AttachedItemCreateResponse response = client
            .attachedItems()
            .create("basic", params);

        AttachedItem attachedItem = response.getAttachedItem();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

const chargebee = new Chargebee({
    site: "{site}",
    apiKey: "{site_api_key}",
});

try {
    const result = await chargebee.attachedItem.create("basic", {
        item_id: "ssl",
        charge_on_event: "subscription_creation",
        charge_once: true
    });

    console.log(result);
    const attachedItem = result.attached_item;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->attachedItem()->create("basic", [
    "item_id" => "ssl",
    "charge_on_event" => "subscription_creation",
    "charge_once" => true
]);
$attachedItem = $result->attached_item;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.AttachedItem.create("basic",
    cb_client.AttachedItem.CreateParams(
        item_id="ssl",
        charge_on_event=chargebee.ChargeOnEvent.SUBSCRIPTION_CREATION,
        charge_once=True
    )
)
attached_item = response.attached_item
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::AttachedItem.create("basic",{
  :item_id => "ssl",
  :charge_on_event => "SUBSCRIPTION_CREATION",
  :charge_once => "true"
})

attached_item = result.attached_item
```

## Sample Response

```json
{
  "attached_item": {
    "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
  }
}
```

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

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

- `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 parameter. This parameter, in turn, has a higher precedence than [the value set for the addon-item price](/docs/api/item_prices) .

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

- `charge_on_event` (optional, enumerated string)
  Indicates when the item is charged. This parameter 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 parameter only applies to charge-items.

- `business_entity_id` (optional, string, max chars=50)
  The unique ID of the [business entity](/docs/api/business_entities) 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](/docs/api/advanced-features) or [query string parameter](/docs/api/advanced-features#mbe-alternative).

## Returns

- `attached_item` (Attached item object)
  Resource object representing attached\_item