Skip to main content
POST
/
customs
/
items
cURL
curl  https://api.goshippo.com/customs/items/ \
-H "Authorization: ShippoToken <API_TOKEN>" \
-d description="T-Shirt" \
-d quantity=2 \
-d net_weight="400" \
-d mass_unit="g" \
-d value_amount="20" \
-d value_currency="USD" \
-d tariff_number="" \
-d origin_country="US" \
-d metadata="Order ID '123123'"
import shippo
from shippo.models import components

s = shippo.Shippo(
    api_key_header='ShippoToken <API_TOKEN>',
    shippo_api_version='2018-02-08',
)


res = s.customs_items.create(request=components.CustomsItemCreateRequest(
    description='T-Shirt',
    mass_unit=components.WeightUnitEnum.LB,
    metadata='Order ID "123454"',
    net_weight='5',
    origin_country='<value>',
    quantity=20,
    sku_code='HM-123',
    hs_code='0901.21',
    value_amount='200',
    value_currency='USD',
))

if res is not None:
    # handle response
    pass
import { Shippo } from "shippo";

const shippo = new Shippo({
  apiKeyHeader: "ShippoToken <API_TOKEN>",
  shippoApiVersion: "2018-02-08",
});

async function run() {
  const result = await shippo.customsItems.create({
    description: "T-Shirt",
    massUnit: "lb",
    metadata: "Order ID \"123454\"",
    netWeight: "5",
    originCountry: "<value>",
    quantity: 20,
    skuCode: "HM-123",
    hsCode: "0901.21",
    valueAmount: "200",
    valueCurrency: "USD",
  });

  // Handle the result
  console.log(result);
}

run();
declare(strict_types=1);

require 'vendor/autoload.php';

use Shippo\API;
use Shippo\API\Models\Components;

$sdk = API\Shippo::builder()
    ->setSecurity(
        'ShippoToken <API_TOKEN>'
    )
    ->setShippoApiVersion('2018-02-08')
    ->build();

$customsItemCreateRequest = new Components\CustomsItemCreateRequest(
    description: 'T-Shirt',
    massUnit: Components\WeightUnitEnum::Lb,
    metadata: 'Order ID "123454"',
    netWeight: '5',
    originCountry: '<value>',
    quantity: 20,
    skuCode: 'HM-123',
    hsCode: '0901.21',
    valueAmount: '200',
    valueCurrency: 'USD',
);

$response = $sdk->customsItems->create(
    customsItemCreateRequest: $customsItemCreateRequest,
    shippoApiVersion: '2018-02-08'

);

if ($response->customsItem !== null) {
    // handle response
}
using Shippo;
using Shippo.Models.Components;

var sdk = new ShippoSDK(
    apiKeyHeader: "ShippoToken <API_TOKEN>",
    shippoApiVersion: "2018-02-08"
);

var res = await sdk.CustomsItems.CreateAsync(
    customsItemCreateRequest: new CustomsItemCreateRequest() {
        Description = "T-Shirt",
        MassUnit = WeightUnitEnum.Lb,
        Metadata = "Order ID \"123454\"",
        NetWeight = "5",
        OriginCountry = "<value>",
        Quantity = 20,
        SkuCode = "HM-123",
        HsCode = "0901.21",
        ValueAmount = "200",
        ValueCurrency = "USD",
    },
    shippoApiVersion: "2018-02-08"
);

// handle response
package hello.world;

import com.goshippo.shippo_sdk.Shippo;
import com.goshippo.shippo_sdk.models.components.CustomsItemCreateRequest;
import com.goshippo.shippo_sdk.models.components.WeightUnitEnum;
import com.goshippo.shippo_sdk.models.operations.CreateCustomsItemResponse;
import java.lang.Exception;

public class Application {

    public static void main(String[] args) throws Exception {

        Shippo sdk = Shippo.builder()
                .apiKeyHeader("ShippoToken <API_TOKEN>")
                .shippoApiVersion("2018-02-08")
            .build();

        CreateCustomsItemResponse res = sdk.customsItems().create()
                .shippoApiVersion("2018-02-08")
                .customsItemCreateRequest(CustomsItemCreateRequest.builder()
                    .description("T-Shirt")
                    .massUnit(WeightUnitEnum.LB)
                    .netWeight("5")
                    .originCountry("<value>")
                    .quantity(20L)
                    .valueAmount("200")
                    .valueCurrency("USD")
                    .metadata("Order ID \"123454\"")
                    .skuCode("HM-123")
                    .hsCode("0901.21")
                    .build())
                .call();

        if (res.customsItem().isPresent()) {
            // handle response
        }
    }
}
const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    description: 'T-Shirt',
    mass_unit: 'lb',
    net_weight: '5',
    origin_country: '<string>',
    quantity: 20,
    value_amount: '200',
    value_currency: 'USD',
    eccn_ear99: '<string>',
    metadata: 'Order ID "123454"',
    sku_code: 'HM-123',
    hs_code: '0901.21',
    tariff_number: '<string>'
  })
};

fetch('https://api.goshippo.com/customs/items', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.goshippo.com/customs/items"

	payload := strings.NewReader("{\n  \"description\": \"T-Shirt\",\n  \"mass_unit\": \"lb\",\n  \"net_weight\": \"5\",\n  \"origin_country\": \"<string>\",\n  \"quantity\": 20,\n  \"value_amount\": \"200\",\n  \"value_currency\": \"USD\",\n  \"eccn_ear99\": \"<string>\",\n  \"metadata\": \"Order ID \\\"123454\\\"\",\n  \"sku_code\": \"HM-123\",\n  \"hs_code\": \"0901.21\",\n  \"tariff_number\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
require 'uri'
require 'net/http'

url = URI("https://api.goshippo.com/customs/items")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"description\": \"T-Shirt\",\n  \"mass_unit\": \"lb\",\n  \"net_weight\": \"5\",\n  \"origin_country\": \"<string>\",\n  \"quantity\": 20,\n  \"value_amount\": \"200\",\n  \"value_currency\": \"USD\",\n  \"eccn_ear99\": \"<string>\",\n  \"metadata\": \"Order ID \\\"123454\\\"\",\n  \"sku_code\": \"HM-123\",\n  \"hs_code\": \"0901.21\",\n  \"tariff_number\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body
{
  "description": "T-Shirt",
  "mass_unit": "lb",
  "net_weight": "5",
  "origin_country": "<string>",
  "quantity": 20,
  "value_amount": "200",
  "value_currency": "USD",
  "eccn_ear99": "<string>",
  "metadata": "Order ID \"123454\"",
  "sku_code": "HM-123",
  "hs_code": "0901.21",
  "tariff_number": "<string>",
  "object_created": "2014-07-17T00:49:20.631Z",
  "object_id": "d799c2679e644279b59fe661ac8fa488",
  "object_owner": "shippotle@shippo.com",
  "object_updated": "2014-07-17T00:49:20.631Z",
  "test": true
}
{}

Authorizations

Authorization
string
header
default:ShippoToken
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json

CustomsItem details.

description
string
required

Text description of your item.

Example:

"T-Shirt"

mass_unit
enum<string>
required

The unit used for weight.

Available options:
g,
kg,
lb,
oz
Example:

"lb"

net_weight
string
required

Total weight of this item, i.e. quantity * weight per item.

Example:

"5"

origin_country
string
required

Country of origin of the item. Example: US or DE. All accepted values can be found on the Official ISO Website.

quantity
integer<int64>
required

Quantity of this item in the shipment you send. Must be greater than 0.

Example:

20

value_amount
string
required

Total value of this item, i.e. quantity * value per item.

Example:

"200"

value_currency
string
required

Currency used for value_amount. The official ISO 4217 currency codes are used, e.g. USD or EUR.

Example:

"USD"

eccn_ear99
string

Export Control Classification Number, required on some exports from the United States.

metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Example:

"Order ID \"123454\""

sku_code
string

SKU code of the item, which is required by some carriers.

Example:

"HM-123"

hs_code
string

HS code of the item, which is required by some carriers. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 50 character limit.

Example:

"0901.21"

tariff_number
string

The tariff number of the item. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 12 character limit.

Response

Customs item

description
string
required

Text description of your item.

Example:

"T-Shirt"

mass_unit
enum<string>
required

The unit used for weight.

Available options:
g,
kg,
lb,
oz
Example:

"lb"

net_weight
string
required

Total weight of this item, i.e. quantity * weight per item.

Example:

"5"

origin_country
string
required

Country of origin of the item. Example: US or DE. All accepted values can be found on the Official ISO Website.

quantity
integer<int64>
required

Quantity of this item in the shipment you send. Must be greater than 0.

Example:

20

value_amount
string
required

Total value of this item, i.e. quantity * value per item.

Example:

"200"

value_currency
string
required

Currency used for value_amount. The official ISO 4217 currency codes are used, e.g. USD or EUR.

Example:

"USD"

eccn_ear99
string

Export Control Classification Number, required on some exports from the United States.

metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Example:

"Order ID \"123454\""

sku_code
string

SKU code of the item, which is required by some carriers.

Example:

"HM-123"

hs_code
string

HS code of the item, which is required by some carriers. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 50 character limit.

Example:

"0901.21"

tariff_number
string

The tariff number of the item. If tariff_number is not provided, hs_code will be used. If both hs_code and tariff_number are provided, tariff_number will be used. 12 character limit.

object_created
string<date-time>

Date and time of object creation.

Example:

"2014-07-17T00:49:20.631Z"

object_id
string

Unique identifier of the given object.

Example:

"d799c2679e644279b59fe661ac8fa488"

object_owner
string

Username of the user who created the object.

Example:

"shippotle@shippo.com"

object_state
enum<string>

Indicates the validity of the enclosing object

Available options:
VALID,
INVALID
object_updated
string<date-time>

Date and time of last object update.

Example:

"2014-07-17T00:49:20.631Z"

test
boolean

Indicates whether the object has been created in test mode.