# Create an item

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


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

Creates a new item.

## Sample Request

### create a plan item.

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="silver" \
     -d name="Silver" \
     -d type="PLAN" \
     -d item_family_id="acme-inc" \
     -d item_applicability="ALL"
```

#### .NET

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

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Item.Create()
		.Id("silver")
		.Name("Silver")
		.Type(Item.TypeEnum.Plan)
		.ItemFamilyId("acme-inc")
		.ItemApplicability(Item.ItemApplicabilityEnum.All)
		.Request();

Item item = result.Item;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    itemAction "github.com/chargebee/chargebee-go/v3/actions/item"
    "github.com/chargebee/chargebee-go/v3/models/item"
    itemEnum "github.com/chargebee/chargebee-go/v3/models/item/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := itemAction.Create(&item.CreateRequestParams{
        Id : "silver",
        Name : "Silver",
        Type : itemEnum.TypePlan,
        ItemFamilyId : "acme-inc",
        ItemApplicability : itemEnum.ItemApplicabilityAll,
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        Item := res.Item
    }
}
```

#### 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.ItemCreateRequest{
    Id : "silver",
    Name : "Silver",
    Type : chargebee.ItemTypePlan,
    ItemFamilyId : "acme-inc",
    ItemApplicability : chargebee.ItemItemApplicabilityAll,
}
  res, err := client.Item.Create(req)
      if err != nil {
        fmt.Println(err)
    } else {
        Item := res.Item
    }
}
```

#### 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 = Item.create()
            .id("silver")
            .name("Silver")
            .type(Item.Type.PLAN)
            .itemFamilyId("acme-inc")
            .itemApplicability(Item.ItemApplicability.ALL)
            .request();

        Item item = result.item();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.item.Item;
import com.chargebee.v4.models.item.params.ItemCreateParams;
import com.chargebee.v4.models.item.responses.ItemCreateResponse;

public class ItemCreate {

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

        ItemCreateParams params = ItemCreateParams.builder()
            .id("silver")
            .name("Silver")
            .type(ItemCreateParams.Type.PLAN)
            .itemFamilyId("acme-inc")
            .itemApplicability(ItemCreateParams.ItemApplicability.ALL)
            .build();

        ItemCreateResponse response = client.items().create(params);

        Item item = response.getItem();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

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

try {
    const result = await chargebee.item.create({
        id: "silver",
        name: "Silver",
        type: "plan",
        item_family_id: "acme-inc",
        item_applicability: "all"
    });

    console.log(result);
    const item = result.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->item()->create([
    "id" => "silver",
    "name" => "Silver",
    "type" => "plan",
    "item_family_id" => "acme-inc",
    "item_applicability" => "all"
]);
$item = $result->item;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Item.create(
    cb_client.Item.CreateParams(
        id="silver",
        name="Silver",
        type=chargebee.Item.Type.PLAN,
        item_family_id="acme-inc",
        item_applicability=chargebee.Item.ItemApplicability.ALL
    )
)
item = response.item
```

#### Ruby

```ruby
require 'chargebee'

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

result = ChargeBee::Item.create({
  :id => "silver",
  :name => "Silver",
  :type => "PLAN",
  :item_family_id => "acme-inc",
  :item_applicability => "ALL"
})

item = result.item
```

### create an addon item

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="ssl" \
     -d name="ssl" \
     -d type="ADDON" \
     -d item_family_id="acme-inc"
```

#### .NET

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

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Item.Create()
		.Id("ssl")
		.Name("ssl")
		.Type(Item.TypeEnum.Addon)
		.ItemFamilyId("acme-inc")
		.Request();

Item item = result.Item;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    itemAction "github.com/chargebee/chargebee-go/v3/actions/item"
    "github.com/chargebee/chargebee-go/v3/models/item"
    itemEnum "github.com/chargebee/chargebee-go/v3/models/item/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := itemAction.Create(&item.CreateRequestParams{
        Id : "ssl",
        Name : "ssl",
        Type : itemEnum.TypeAddon,
        ItemFamilyId : "acme-inc",
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        Item := res.Item
    }
}
```

#### 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.ItemCreateRequest{
    Id : "ssl",
    Name : "ssl",
    Type : chargebee.ItemTypeAddon,
    ItemFamilyId : "acme-inc",
}
  res, err := client.Item.Create(req)
      if err != nil {
        fmt.Println(err)
    } else {
        Item := res.Item
    }
}
```

#### 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 = Item.create()
            .id("ssl")
            .name("ssl")
            .type(Item.Type.ADDON)
            .itemFamilyId("acme-inc")
            .request();

        Item item = result.item();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.item.Item;
import com.chargebee.v4.models.item.params.ItemCreateParams;
import com.chargebee.v4.models.item.responses.ItemCreateResponse;

public class ItemCreate {

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

        ItemCreateParams params = ItemCreateParams.builder()
            .id("ssl")
            .name("ssl")
            .type(ItemCreateParams.Type.ADDON)
            .itemFamilyId("acme-inc")
            .build();

        ItemCreateResponse response = client.items().create(params);

        Item item = response.getItem();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

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

try {
    const result = await chargebee.item.create({
        id: "ssl",
        name: "ssl",
        type: "addon",
        item_family_id: "acme-inc"
    });

    console.log(result);
    const item = result.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->item()->create([
    "id" => "ssl",
    "name" => "ssl",
    "type" => "addon",
    "item_family_id" => "acme-inc"
]);
$item = $result->item;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Item.create(
    cb_client.Item.CreateParams(
        id="ssl",
        name="ssl",
        type=chargebee.Item.Type.ADDON,
        item_family_id="acme-inc"
    )
)
item = response.item
```

#### Ruby

```ruby
require 'chargebee'

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

result = ChargeBee::Item.create({
  :id => "ssl",
  :name => "ssl",
  :type => "ADDON",
  :item_family_id => "acme-inc"
})

item = result.item
```

### create a plan item with restricted applicable addon item

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/items \
     -u {site_api_key}:\
     -d id="gold" \
     -d name="Gold" \
     -d type="PLAN" \
     -d item_family_id="acme-inc" \
     -d item_applicability="RESTRICTED" \
     -d "applicable_items[0]"="day-pass"
```

#### .NET

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

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Item.Create()
		.Id("gold")
		.Name("Gold")
		.Type(Item.TypeEnum.Plan)
		.ItemFamilyId("acme-inc")
		.ItemApplicability(Item.ItemApplicabilityEnum.Restricted)
		.ApplicableItems(new List<string>{"day-pass"})
		.Request();

Item item = result.Item;
```

#### Go

```go
package main
import (
    "fmt"
    "github.com/chargebee/chargebee-go/v3"
    itemAction "github.com/chargebee/chargebee-go/v3/actions/item"
    "github.com/chargebee/chargebee-go/v3/models/item"
    itemEnum "github.com/chargebee/chargebee-go/v3/models/item/enum"
)
func main() {
    chargebee.Configure("{site_api_key}","{site}");
    res,err := itemAction.Create(&item.CreateRequestParams{
        Id : "gold",
        Name : "Gold",
        Type : itemEnum.TypePlan,
        ItemFamilyId : "acme-inc",
        ItemApplicability : itemEnum.ItemApplicabilityRestricted,
        ApplicableItems : []string{"day-pass"},
    }).Request()
    if err != nil {
        fmt.Println(err)
    } else {
        Item := res.Item
    }
}
```

#### 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.ItemCreateRequest{
    Id : "gold",
    Name : "Gold",
    Type : chargebee.ItemTypePlan,
    ItemFamilyId : "acme-inc",
    ItemApplicability : chargebee.ItemItemApplicabilityRestricted,
    ApplicableItems : []string{"day-pass"},
}
  res, err := client.Item.Create(req)
      if err != nil {
        fmt.Println(err)
    } else {
        Item := res.Item
    }
}
```

#### 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 = Item.create()
            .id("gold")
            .name("Gold")
            .type(Item.Type.PLAN)
            .itemFamilyId("acme-inc")
            .itemApplicability(Item.ItemApplicability.RESTRICTED)
            .applicableItems("day-pass")
            .request();

        Item item = result.item();
    }
}
```

#### Java

```java
import com.chargebee.v4.client.ChargebeeClient;
import com.chargebee.v4.models.item.Item;
import com.chargebee.v4.models.item.params.ItemCreateParams;
import com.chargebee.v4.models.item.responses.ItemCreateResponse;
import java.util.List;

public class ItemCreate {

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

        ItemCreateParams params = ItemCreateParams.builder()
            .id("gold")
            .name("Gold")
            .type(ItemCreateParams.Type.PLAN)
            .itemFamilyId("acme-inc")
            .itemApplicability(ItemCreateParams.ItemApplicability.RESTRICTED)
            .applicableItems(List.of("day-pass"))
            .build();

        ItemCreateResponse response = client.items().create(params);

        Item item = response.getItem();
    }
}
```

#### Node.js

```node
import Chargebee from "chargebee";

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

try {
    const result = await chargebee.item.create({
        id: "gold",
        name: "Gold",
        type: "plan",
        item_family_id: "acme-inc",
        item_applicability: "restricted",
        applicable_items: ["day-pass"]
    });

    console.log(result);
    const item = result.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->item()->create([
    "id" => "gold",
    "name" => "Gold",
    "type" => "plan",
    "item_family_id" => "acme-inc",
    "item_applicability" => "restricted",
    "applicable_items" => ["day-pass"]
]);
$item = $result->item;
```

#### Python

```python
import chargebee
from chargebee import Chargebee

cb_client = Chargebee(api_key="{site_api_key}", site="{site}")
response = cb_client.Item.create(
    cb_client.Item.CreateParams(
        id="gold",
        name="Gold",
        type=chargebee.Item.Type.PLAN,
        item_family_id="acme-inc",
        item_applicability=chargebee.Item.ItemApplicability.RESTRICTED,
        applicable_items=["day-pass"]
    )
)
item = response.item
```

#### Ruby

```ruby
require 'chargebee'

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

result = ChargeBee::Item.create({
  :id => "gold",
  :name => "Gold",
  :type => "PLAN",
  :item_family_id => "acme-inc",
  :item_applicability => "RESTRICTED",
  :applicable_items => ["day-pass"]
})

item = result.item
```

## Sample Response

```json
{
  "item": {
    "enabled_for_checkout": true,
    "enabled_in_portal": true,
    "id": "silver",
    "is_giftable": false,
    "is_shippable": false,
    "item_applicability": "all",
    "name": "Silver",
    "object": "item",
    "resource_version": 1599817249982,
    "status": "active",
    "type": "plan",
    "updated_at": 1599817249
  }
}
```

## URL Format

**POST** https://[site].chargebee.com/api/v2/items

## Input Parameters

- `id` (required, string, max chars=100)
  The identifier for the item. Must be unique and is immutable once set.

- `name` (required, string, max chars=100)
  A unique display name for the item. Must be unique. This is visible only in Chargebee and not to customers.

- `type` (required, enumerated string)
  The type of the item.
  Possible enum values:
    - `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](/docs/api/v2/pcv-1/invoices/create-invoice-for-a-one-time-charge) without being applied to a subscription.

- `description` (optional, string, max chars=2000)
  Description of the item. This is visible only in Chargebee and not to customers.

- `item_family_id` (required, string, max chars=100)
  The `id` of the [Item family](/docs/api/item_families) that the item belongs to. Is mandatory when [Product Families](https://www.chargebee.com/docs/2.0/product-families.html) have been enabled.

- `is_giftable` (optional, boolean, default=false)
  Specifies if gift subscriptions can be created for this item.

- `is_shippable` (optional, boolean, default=false)
  Indicates that the item is a physical product. If Orders are enabled in Chargebee, subscriptions created for this item will have orders associated with them.

- `external_name` (optional, string, max chars=100)
  A unique display name for the item.

- `enabled_in_portal` (optional, boolean, default=true)
  Allow customers to change their subscription to this plan via the [Self-Serve Portal](https://www.chargebee.com/docs/2.0/inapp-self-serve-portal.html). Applies only for plan-items. This requires the Portal configuration to [allow changing subscriptions](https://www.chargebee.com/docs/2.0/inapp-self-serve-portal.html#allow-change-subscription). Only the in-app version of the Portal is supported for Product Catalog v2.

- `redirect_url` (optional, string, max chars=500)
  If `enabled_for_checkout` , then the URL to be redirected to once the checkout is complete. This attribute is only available for plan-items.

- `enabled_for_checkout` (optional, boolean, default=true)
  Allow the plan to subscribed to via Checkout. Applies only for plan-items. **Note:** Only the in-app layout of Checkout is supported.

- `item_applicability` (optional, enumerated string, default=all)
  Indicates which addon-items and charge-items can be applied to the item. Only possible for plan-items. Other details of attaching items such as whether to attach as a mandatory item or to attach on a certain event, can be specified using the [Create](/docs/api/attached_items/create-an-attached-item) or [Update an attached item](/docs/api/attached_items/update-an-attached-item) API.
  Possible enum values:
    - `all`
      all addon-items and charge-items are applicable to this plan-item.
    - `restricted`
      only the addon-items or charge-items provided in `applicable_items` can be applied to this plan-item.

- `applicable_items` (optional, string, max chars=100)
  The list of ids of addon-items and charge-items that can be applied to the plan-item. This parameter can be provided only for plan-items and that too when item\_applicability is restricted. Other details of attaching items can be specified using the [Create](/docs/api/attached_items/create-an-attached-item) or [Update an attached item](/docs/api/attached_items/update-an-attached-item) API.

- `unit` (optional, string, max chars=30)
  The unit of measure for a quantity-based item. This is displayed on the Chargebee UI and on customer facing documents/pages. The latter includes [hosted pages](/docs/api/hosted_pages) , [invoices](/docs/api/invoices) and [quotes](/docs/api/quotes). Examples follow:
  
  -   "user" for a cloud-collaboration platform.
  -   "GB" for a data service.
  -   "issue" for a magazine.

- `gift_claim_redirect_url` (optional, string, max chars=500)
  The URL to redirect to once the gift has been claimed by the receiver.

- `included_in_mrr` (optional, boolean)
  The item is included in MRR calculations for your site. This attribute is only applicable for items of `type = charge` and when the feature is enabled in Chargebee. Note: If the site-level setting is to exclude charge-items from MRR calculations, this value is always returned `false` .

- `metered` (optional, boolean, default=false)
  Specifies whether the item undergoes usage-based or metered billing. [Usage Based Billing](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/understanding-usages) or [Metered Billing](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/metered_billing) must be enabled on your site to set `metered` to `true`.
  
  **Usage Based Billing**
  
  When Usage Based Billing is enabled, `metered` is applicable only for items of `type` `addon`. When `true`, the quantity is calculated from [usage events](/docs/api/usage_events/create-a-usage-event). When `false`, you must provide the quantity when adding an [item price](/docs/api/item_prices) that belongs to this item to a subscription (for example, when [creating](/docs/api/subscriptions/create-subscription-for-items#subscription_items_quantity) or [updating](/docs/api/subscriptions/update-subscription-for-items#subscription_items_quantity) the subscription).
  
  **Metered Billing**
  
  When Metered Billing is enabled, `metered` is applicable only for items of `type` `plan` or `addon`. When `true`, the quantity is calculated from [usage records](/docs/api/usages). When `false`, you must provide the quantity when adding an [item price](/docs/api/item_prices) that belongs to this item to a subscription (for example, when [creating](/docs/api/subscriptions/create-subscription-for-items#subscription_items_quantity) or [updating](/docs/api/subscriptions/update-subscription-for-items#subscription_items_quantity) the subscription).

- `usage_calculation` (optional, enumerated string)
  How the quantity is calculated from usage data for the item prices belonging to this item. Only applicable when the item is `metered`. This value overrides the one [set at the site level](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/metered_billing#configuring-metered-billing). .
  Possible enum values:
    - `sum_of_usages`
      the net quantity is the sum of the `quantity` of all usages for the current term.
    - `last_usage`
      from among the usage records for the [item price](/docs/api/subscriptions/subscription-object#subscription_items_item_price_id) with `usage_date` within the relevant billing period, the `quantity` of the usage record with the most recent `usage_date` is taken as the net quantity consumed.
    - `max_usage`
      from among the usage records for the [item price](/docs/api/subscriptions/subscription-object#subscription_items_item_price_id) with `usage_date` within the relevant billing period, the `quantity` of the usage record with the maximum value is taken as the net quantity consumed.

- `is_percentage_pricing` (optional, boolean, default=false)
  Indicates whether the pricing is percentage-based.

- `metadata` (optional, jsonobject)
  A collection of key-value pairs that provides extra information about the item.
  
  **Note:** There's a character limit of 65,535.
  
  [Learn more](/docs/api/advanced-features#metadata).

- `business_entity_id` (optional, string, max chars=50)
  The unique ID of the [business entity](/docs/api/business_entities) for this `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 means of a [custom HTTP header](/docs/api/advanced-features#mbe-header-main).

- `bundle_configuration` (optional, enumerated string)
  Parameters of `bundle_configuration`
  - `type` (optional, enumerated string)
    Type of the bundle
    Possible enum values:
      - `fixed`
        Fixed `bundle_configuration.type` appears when you create a [bundle plan](https://www.chargebee.com/docs/2.0/product-bundling-overview.html) that cannot be updated during checkout or subscription creation.

- `bundle_items_to_add` (optional, array)
  Parameters for `bundle_items_to_add`
  - `item_id` (optional, string, max chars=100)
    [`item_id`](/docs/api/items/item-object#id) that needs to be added to the bundle. **Note:** This parameter is only applicable when the [`item_type`](/docs/api/items/item-object#type) is `plan` .
  - `item_type` (optional, enumerated string)
    [`item_type`](/docs/api/items/item-object#type) that can be added to the bundle.
    Possible enum values:
      - `plan`
        An essential component of the bundle plan. **Note:** At least one [`plan`](/docs/api/items/item-object#type) item must be associated with the bundle.
      - `addon`
        A recurring component that can be added to a bundle plan.
      - `charge`
        A non-recurring component that can be added to a bundle plan.
  - `quantity` (optional, integer)
    Quantity of the item(plan, addon, and charge) associated with the bundle.
  - `price_allocation` (optional, bigdecimal)
    Price allocation of the item(plan, addon, and charge) associated with the bundle.

## Returns

- `item` (Item object)
  Resource object representing item