# CustomsInfo

`CustomsInfo` objects contain
  `CustomsItem`
 objects and all necessary information for the generation of customs forms required for international shipping.

Please see the `Shipments` documentation for examples of including a `CustomsInfo` object in a `Shipment`.
**Note:** the maximum number of items that can be included in customs info with UPS is 100.

---

## CustomsInfo object

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique, begins with 'cstinfo_' |
| object | string | 'CustomsInfo' |
| eel_pfc | string | "EEL" or "PFC" If value is less than $2500: "NOEEI 30.37(a)" If value is greater than $2500: see Customs Guide |
| contents_type | string | Possible values: "documents" "gift" "merchandise" "returned_goods" "sample" "dangerous_goods" "humanitarian_donation" "other" |
| contents_explanation | string | Human readable description of content, max 255 characters. Required for certain carriers and always required if contents_type is "other" |
| customs_certify | boolean | Electronically certify the information provided |
| customs_signer | string | Required if customs_certify is true |
| non_delivery_option | string | Possible values: "return" (default) "abandon" |
| restriction_type | string | Possible values: "none" "other" "quarantine" "sanitary_phytosanitary_inspection" |
| restriction_comments | string | Required if restriction_type is not "none" |
| customs_items | CustomsItem array | Describes products being shipped |
| declaration | string | A customs declaration message, available for eligible carriers |
| created_at | datetime | When the CustomsInfo was created |
| updated_at | datetime | When the CustomsInfo was last updated |

Example Object:

```json
{
  "id": "cstinfo_400bef43bd354af1a1bcb3f9e8922ee5",
  "object": "CustomsInfo",
  "created_at": "2025-05-09T20:39:15Z",
  "updated_at": "2025-05-09T20:39:15Z",
  "contents_explanation": "",
  "contents_type": "merchandise",
  "customs_certify": true,
  "customs_signer": "Steve Brule",
  "eel_pfc": "NOEEI 30.37(a)",
  "non_delivery_option": "return",
  "restriction_comments": null,
  "restriction_type": "none",
  "mode": "test",
  "declaration": null,
  "customs_items": [
    {
      "id": "cstitem_a0d181241efc422399dd66c993dee32e",
      "object": "CustomsItem",
      "created_at": "2025-05-09T20:39:15Z",
      "updated_at": "2025-05-09T20:39:15Z",
      "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 CustomsInfo

### Example: POST /customs_infos

#### cURL

```shell
curl -X POST https://api.easypost.com/v2/customs_infos \
  -u "EASYPOST_API_KEY": \
  -H 'Content-Type: application/json' \
  -d '{
    "customs_info": {
      "customs_certify": "true",
      "customs_signer": "Steve Brule",
      "contents_type": "merchandise",
      "contents_explanation": "",
      "restriction_type": "none",
      "eel_pfc": "NOEEI 30.37(a)",
      "customs_items": [
        {
          "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")

	customsInfo, _ := client.CreateCustomsInfo(
		&easypost.CustomsInfo{
			CustomsCertify:      true,
			CustomsSigner:       "Steve Brule",
			ContentsType:        "merchandise",
			ContentsExplanation: "",
			RestrictionType:     "none",
			EELPFC:              "NOEEI 30.37(a)",
			CustomsItems: []*easypost.CustomsItem{
				&easypost.CustomsItem{
					Description:   "T-shirt",
					Quantity:      1,
					Value:         10.00,
					Weight:        5,
					OriginCountry: "US",
				},
			},
		},
	)

	fmt.Println(customsInfo)
}
```

#### Java

```java
package customs_info;

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

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;

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

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

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

        List<CustomsItem> customsItemsList = new ArrayList<CustomsItem>();
        customsItemsList.add(customsItem);

        HashMap<String, Object> params = new HashMap<String, Object>();
        params.put("customs_certify", true);
        params.put("customs_signer", "Steve Brule");
        params.put("contents_type", "merchandise");
        params.put("contents_explanation", "");
        params.put("eel_pfc", "NOEEI 30.37(a)");
        params.put("restriction_type", "none");
        params.put("customs_items", customsItemsList);

        CustomsInfo customsInfo = client.customsInfo.create(params);

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

#### 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.CustomsInfo.Create parameters = new()
            {
                CustomsCertify = true,
                CustomsSigner = "Steve Brule",
                ContentsType = "merchandise",
                ContentsExplanation = "",
                RestrictionType = "none",
                EelPfc = "NOEEI 30.37(a)",
                CustomsItems = new List<EasyPost.Parameters.CustomsItem.Create>()
                {
                    new()
                    {
                        Description = "T-shirt",
                        Quantity = 1,
                        Weight = 5,
                        Value = 10,
                        HsTariffNumber = "123456",
                        OriginCountry = "US"
                    }
                }
            };

            EasyPost.Models.API.CustomsInfo customsInfo = await client.CustomsInfo.Create(parameters);

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const customsInfo = await client.CustomsInfo.create({
    eel_pfc: 'NOEEI 30.37(a)',
    customs_certify: true,
    customs_signer: 'Steve Brule',
    contents_type: 'merchandise',
    contents_explanation: '',
    restriction_type: 'none',
    restriction_comments: '',
    customs_items: [
      {
        description: 'T-shirts',
        quantity: 1,
        weight: 5,
        value: 10,
        hs_tariff_number: '123456',
        origin_country: 'US',
      },
    ],
  });

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

#### PHP

```php
<?php

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

$customsInfo = $client->customsInfo->create([
    'eel_pfc' => 'NOEEI 30.37(a)',
    'customs_certify' => true,
    'customs_signer' => 'Steve Brule',
    'contents_type' => 'merchandise',
    'contents_explanation' => '',
    'restriction_type' => 'none',
    'customs_items' => [
        [
            'description' => 'T-shirt',
            'quantity' => 1,
            'weight' => 5,
            'value' => 10,
            'hs_tariff_number' => '123456',
            'origin_country' => 'US'
        ]
    ]
]);

echo $customsInfo;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

customs_info = client.customs_info.create(
    eel_pfc="NOEEI 30.37(a)",
    customs_certify=True,
    customs_signer="Steve Brule",
    contents_type="merchandise",
    contents_explanation="",
    restriction_type="none",
    customs_items=[
        {
            "description": "Sweet shirts",
            "quantity": 2,
            "weight": 11,
            "value": 23,
            "hs_tariff_number": "654321",
            "origin_country": "US",
        }
    ],
)

print(customs_info)
```

#### Ruby

```ruby
require 'easypost'

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

customs_info = client.customs_info.create(
  customs_certify: true,
  customs_signer: 'Steve Brule',
  contents_type: 'merchandise',
  contents_explanation: '',
  restriction_type: 'none',
  eel_pfc: 'NOEEI 30.37(a)',
  customs_items: [
    {
      description: 'T-shirt',
      quantity: 1,
      weight: 5,
      value: 10,
      hs_tariff_number: '123456',
      origin_country: 'US',
    },
  ],
)

puts customs_info
```

A `CustomsInfo` object contains all administrative information for processing customs, as well as a list of `CustomsItems`.
When creating a `CustomsInfo`, you may store the `id` from the response for use later in `Shipment` creation.

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

---

## Retrieve a CustomsInfo

### Example: GET /customs_infos/:id

#### cURL

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

#### Go

```go
package example

import (
	"fmt"

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

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

	customsInfo, _ := client.GetCustomsInfo("cstinfo_...")

	fmt.Println(customsInfo)
}
```

#### Java

```java
package customs_info;

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

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

        CustomsInfo customsInfo = client.customsInfo.retrieve("cstinfo_...");

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

#### 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.CustomsInfo customsInfo = await client.CustomsInfo.Retrieve("cstinfo_...");

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

#### Node.js

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

const client = new EasyPostClient('EASYPOST_API_KEY');

(async () => {
  const customsInfo = await client.CustomsInfo.retrieve('cstinfo_...');

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

#### PHP

```php
<?php

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

$customsInfo = $client->customsInfo->retrieve('cstinfo_...');

echo $customsInfo;
```

#### Python

```python
import easypost

client = easypost.EasyPostClient("EASYPOST_API_KEY")

customs_info = client.customs_info.retrieve("cstinfo_...")

print(customs_info)
```

#### Ruby

```ruby
require 'easypost'

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

customs_info = client.customs_info.retrieve('cstinfo_...')

puts customs_info
```

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