# CustomsItem

A `CustomsItem` object describes goods for international shipment and should be created then included in a `CustomInfo` object.
The `value` on each item can also supply product value for USPS Claims when a customs form is already on the shipment. New claims integrations should send `line_items`.

---

## CustomsItems object

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique, begins with 'cstitem_' |
| object | string | 'CustomsItem' |
| description | string | Description of item being shipped |
| quantity | float | Must be greater than zero |
| value | float (USD) | Total value (unit value * quantity). Must be greater than zero. EasyPost can use this amount as product value for USPS Claims when the item is on the shipment's CustomsInfo. |
| weight | float (oz) | Total line weight in ounces (not per-unit weight). Up to three decimal places are retained; additional decimals are truncated, not rounded. Values smaller than 0.001 oz become 0. Submit positive weights for shippable items; acceptance of a zero-valued object does not establish that shipment can be purchased. Carrier integrations may convert units and apply additional rounding or minimums, so API acceptance does not guarantee every carrier receives the original value unchanged. |
| hs_tariff_number | string | Harmonized Tariff Schedule code used to classify goods for customs declarations. Typically 6 or 10 digits, e.g. "6109.10.0012". |
| code | string | SKU, UPC or other product identifier |
| manufacturer | string | Manufacturer of item |
| eccn | string | Export Control Classification Number |
| printed_commodity_identifier | string | International commodity code |
| origin_country | string | Two-character country code |
| currency | string | Three-character currency code. Defaults to "USD" |
| created_at | datetime | When the CustomsItem was created |
| updated_at | datetime | When the CustomsItem was last updated |

Example Object:

```json
{
  "id": "cstitem_4e7df04b42fa4ad4a2212620e0d8b78f",
  "object": "CustomsItem",
  "created_at": "2025-05-09T20:39:16Z",
  "updated_at": "2025-05-09T20:39:16Z",
  "description": "T-shirt",
  "hs_tariff_number": "123456",
  "origin_country": "US",
  "quantity": 1,
  "value": "10.0",
  "weight": 5.0,
  "code": "123",
  "mode": "test",
  "manufacturer": null,
  "currency": null,
  "eccn": null,
  "printed_commodity_identifier": null
}
```

---

## Create a CustomsItem

### Example: POST /customs_items

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/customs_items \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "customs_item": {
      "description": "T-shirt",
      "quantity": "1",
      "weight": "5",
      "value": "10",
      "hs_tariff_number": "123456",
      "origin_country": "US"
    }
  }'
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func create() {
	client := easypost.New("EASYPOST_API_KEY")

	customsItem, _ := client.CreateCustomsItem(
		&easypost.CustomsItem{
			Description:   "T-shirts",
			Quantity:      1,
			Value:         10.00,
			Weight:        5,
			OriginCountry: "US",
		},
	)

	fmt.Println(customsItem)
}
```

#### Java

```java
package customs_items;

import com.easypost.exception.EasyPostException;
import com.easypost.model.CustomsItem;
import com.easypost.service.EasyPostClient;

import java.util.HashMap;

public class Create {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        HashMap<String, Object> params = new HashMap<String, Object>();
        params.put("description", "T-shirt");
        params.put("quantity", 1);
        params.put("value", 10);
        params.put("weight", 5);
        params.put("origin_country", "US");
        params.put("hs_tariff_number", "123456");

        CustomsItem customsItem = client.customsItem.create(params);

        System.out.println(customsItem);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Parameters.CustomsItems.Create parameters = new()
            {
                Description = "T-shirt",
                Quantity = 1,
                Weight = 5,
                Value = 10,
                HsTariffNumber = "123456",
                OriginCountry = "US"
            };

            EasyPost.Models.API.CustomsItem customsItem = await client.CustomsItem.Create(parameters);

            Console.WriteLine(JsonConvert.SerializeObject(customsItem, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const customsItem = await client.CustomsItem.create({
    description: 'T-shirt',
    quantity: 1,
    value: 10,
    weight: 5,
    hs_tariff_number: '123456',
    origin_country: 'us',
  });

  console.log(customsItem);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$customsItem = $client->customsItem->create([
    'description' => 'T-shirt',
    'quantity' => 1,
    'weight' => 5,
    'value' => 10,
    'hs_tariff_number' => '123456',
    'origin_country' => 'US'
]);

echo $customsItem;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

customs_item = client.customs_item.create(
    description="T-shirt",
    quantity=1,
    value=10,
    weight=5,
    hs_tariff_number="123456",
    origin_country="us",
)

print(customs_item)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

customs_item = client.customs_item.create(
  description: 'T-shirt',
  quantity: 1,
  weight: 5,
  value: 10,
  hs_tariff_number: '123456',
  origin_country: 'us',
)

puts customs_item
```

A `CustomsItem` contains information relating to each product within the package. When creating a `CustomsItem`, you may store the `id` from the response for use later in `CustomsInfo` creation.

[Note: This object is immutable after creation. Review the rendered documentation for details.]

---

## Retrieve a CustomsItem

### Example: GET /customs_items/:id

#### cURL

```shell
curl -X GET https://api.easypost.com/v2/customs_items/cstitem_... \
  -u "EASYPOST_API_KEY":
```

#### Go

```go
package example

import (
	"fmt"

	"github.com/EasyPost/easypost-go/v5"
)

func retrieve() {
	client := easypost.New("EASYPOST_API_KEY")

	customsItem, _ := client.GetCustomsItem("cstitem_...")

	fmt.Println(customsItem)
}
```

#### Java

```java
package customs_items;

import com.easypost.exception.EasyPostException;
import com.easypost.model.CustomsItem;
import com.easypost.service.EasyPostClient;

public class Retrieve {
    public static void main(String[] args) throws EasyPostException {
        EasyPostClient client = new EasyPostClient("EASYPOST_API_KEY");

        CustomsItem customsItem = client.customsItem.retrieve("cstitem_...");

        System.out.println(customsItem);
    }
}
```

#### C#

```csharp
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using EasyPost;
using Newtonsoft.Json;

namespace EasyPostExamples
{
    public class Examples
    {
        public static async Task Main()
        {
            var client = new EasyPost.Client(new EasyPost.ClientConfiguration("EASYPOST_API_KEY"));

            EasyPost.Models.API.CustomsItem customsItem = await client.CustomsItem.Retrieve("cstitem_...");

            Console.WriteLine(JsonConvert.SerializeObject(customsItem, Formatting.Indented));
        }
    }
}
```

#### Node.js

```javascript
const EasyPostClient = require('@easypost/api');

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const customsItem = await client.CustomsItem.retrieve('cstitem_...');

  console.log(customsItem);
})();
```

#### PHP

```php
<?php

$client = new \EasyPost\EasyPostClient('EASYPOST_API_KEY');

$customsItem = $client->customsItem->retrieve('cstitem_...');

echo $customsItem;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

customs_item = client.customs_item.retrieve("cstitem_...")

print(customs_item)
```

#### Ruby

```ruby
require 'easypost'

client = EasyPost::Client.new(api_key: 'EASYPOST_API_KEY')

customs_item = client.customs_item.retrieve('cstitem_...')

puts customs_item
```

A `CustomsItem` can be retrieved by its `id`.