# Create a new customs declaration

Creates a new customs declaration object

Endpoint: POST /customs/declarations
Version: 2018-02-08
Security: APIKeyHeader

## Header parameters:

  - `SHIPPO-API-VERSION` (string)
    Optional string used to pick a non-default API version to use. See our API version guide.
    Example: "2018-02-08"

## Request fields (application/json):

  - `aes_itn` (string)
    required if eel_pfc is AES_ITN
AES / ITN reference of the shipment.

  - `b13a_filing_option` (string)
    B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). 
 More information on reporting commercial exports from Canada. 
Allowed values available here
    Enum: "FILED_ELECTRONICALLY", "SUMMARY_REPORTING", "NOT_REQUIRED"

  - `b13a_number` (string)
    must be provided if and only if b13a_filing_option is provided
Represents: the Proof of Report (POR) Number when b13a_filing_option is FILED_ELECTRONICALLY; 
the Summary ID Number when b13a_filing_option is SUMMARY_REPORTING; 
or the Exemption Number when b13a_filing_option is NOT_REQUIRED.

  - `certificate` (string)
    Certificate reference of the shipment.

  - `certify` (boolean, required)
    Expresses that the certify_signer has provided all information of this customs declaration truthfully.
    Example: true

  - `certify_signer` (string, required)
    Name of the person who created the customs declaration and is responsible for the validity of all 
information provided.
    Example: "Shawn Ippotle"

  - `commercial_invoice` (boolean)

  - `contents_explanation` (string)
    required if contents_type is OTHER
Explanation of the type of goods of the shipment.
    Example: "T-Shirt purchase"

  - `disclaimer` (string)
    Disclaimer for the shipment and customs information that have been provided.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 554 characters |

  - `duties_payor` (object)
    Specifies who will pay the duties for the shipment. Only accepted for FedEx shipments.

  - `duties_payor.account` (string)
    Account number to be billed for duties.
    Example: "2323434543"

  - `duties_payor.type` (any)
    Party to be billed for duties.
    Enum: "SENDER", "RECIPIENT", "THIRD_PARTY"

  - `duties_payor.address` (object)

  - `duties_payor.address.name` (string)
    Name of the party to be billed for duties.
    Example: "Patrick Kavanagh"

  - `duties_payor.address.zip` (string)
    Postal code of the party to be billed for duties.
    Example: "80331"

  - `duties_payor.address.country` (string)
    Country ISO code of account number to be billed.
    Example: "DE"

  - `exporter_identification` (object)
    Additional exporter identification that may be required to ship in certain countries

  - `exporter_identification.eori_number` (string)
    Economic Operators' Registration and Identification (EORI) number. Must start with a 2 character 
country code followed by a 6-17 character alphanumeric identifier (e.g. PL1234567890ABCDE).
More information on EORI.
    Example: "PL123456790ABCDE"

  - `exporter_identification.tax_id` (object)
    Tax identification that may be required to ship in certain countries. Typically used to assess duties on 
goods that are crossing a border.

  - `exporter_identification.tax_id.number` (string)
    Tax identification number.
    Example: "123456789"

  - `exporter_identification.tax_id.type` (any)
    Type of tax identification.
* EIN - Employer Identification Number, also known as a Federal Tax Identification Number.
* VAT - Value Added Tax identification number.
* IOSS - Import One-Stop Shop
* ARN - Australian Taxation Office Reference Number
    Enum: "EIN", "VAT", "IOSS", "ARN"

  - `exporter_reference` (string)
    Exporter reference of an export shipment.

  - `importer_reference` (string)
    Importer reference of an import shipment.

  - `is_vat_collected` (boolean)
    Indicates whether the shipment's destination VAT has been collected. May be required for some destinations.

  - `invoice` (string)
    Invoice reference of the shipment.
    Example: "#123123"

  - `license` (string)
    License reference of the shipment.

  - `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 #123123"

  - `notes` (string)
    Additional notes to be included in the customs declaration.

  - `address_importer` (object)
    Object that represents the address of the importer

  - `address_importer.name` (string)
    First and Last Name of the addressee
    Example: "Shwan Ippotle"

  - `address_importer.company` (string)
    Company Name
    Example: "Shippo"

  - `address_importer.street1` (string)
    First street line, 35 character limit. Usually street number and street name (except for DHL Germany, see street_no).
    Example: "Blumenstraße"

  - `address_importer.street2` (string)
    Second street line, 35 character limit.

  - `address_importer.street3` (string)
    Third street line, 35 character limit. 
Only accepted for USPS international shipments, UPS domestic and UPS international shipments.

  - `address_importer.street_no` (string)
    Street number of the addressed building. 
This field can be included in street1 for all carriers except for DHL Germany.
    Example: "22"

  - `address_importer.city` (string)
    Name of a city
    Example: "München"

  - `address_importer.state` (string)
    required for purchase for some countries
State/Province values are required for shipments from/to the US, AU, and CA. UPS requires province for some 
countries (i.e Ireland). To receive more accurate quotes, passing this field is recommended. Most carriers 
only accept two or three character state abbreviations.
    Example: "CA"

  - `address_importer.zip` (string)
    Postal code of an Address.
    Example: "80331"

  - `address_importer.country` (string)
    Example: US or DE. All accepted values can be found on the 
Official ISO Website.
Sending a country is always required.
    Example: "DE"

  - `address_importer.phone` (string)
    Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This 
increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped.
    Example: "80331"

  - `address_importer.email` (string)
    E-mail address of the contact person, RFC3696/5321-compliant.
    Example: "shippotle@shippo.com"

  - `address_importer.is_residential` (boolean)
    Indicates whether the address provided is a residential address or not.
    Example: true

  - `contents_type` (string, required)
    Type of goods of the shipment.  
Allowed values available here
    Enum: "DOCUMENTS", "GIFT", "SAMPLE", "MERCHANDISE", "HUMANITARIAN_DONATION", "RETURN_MERCHANDISE", "OTHER"

  - `eel_pfc` (string)
    EEL / PFC type of the shipment. For most shipments from the US to CA, NOEEI_30_36 is applicable; for most 
other shipments from the US, NOEEI_30_37_a is applicable.
Allowed values available here
    Enum: "NOEEI_30_37_a", "NOEEI_30_37_h", "NOEEI_30_37_f", "NOEEI_30_36", "AES_ITN"

  - `incoterm` (string)
    The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only.
eDAP is available for DPD UK only. DAP is available for DHL Express, FedEx, and DPD UK.
If expecting DAP for other carriers, please use DDU.
Allowed values available here
Carrier-specific restrictions are in the table below.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Must be one of DDP, DDU, FCA, DAP |
    Enum: "DDP", "DDU", "FCA", "DAP", "eDAP"

  - `items` (array, required)

  - `items.description` (string, required)
    Text description of your item.
    Example: "T-Shirt"

  - `items.eccn_ear99` (string)
    Export Control Classification Number, required on some exports from the United States.

  - `items.mass_unit` (string, required)
    The unit used for weight.
    Enum: "g", "kg", "lb", "oz"

  - `items.net_weight` (string, required)
    Total weight of this item, i.e. quantity * weight per item.
    Example: "5"

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

  - `items.quantity` (integer, required)
    Quantity of this item in the shipment you send.  Must be greater than 0.
    Example: 20

  - `items.sku_code` (string)
    SKU code of the item, which is required by some carriers.
    Example: "HM-123"

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

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

  - `items.value_amount` (string, required)
    Total value of this item, i.e. quantity * value per item.
    Example: "200"

  - `items.value_currency` (string, required)
    Currency used for value_amount. The official ISO 4217 
currency codes are used, e.g.  USD or EUR.
    Example: "USD"

  - `non_delivery_option` (string, required)
    Indicates how the carrier should proceed in case the shipment can't be delivered.
Allowed values available here
    Enum: "ABANDON", "RETURN"

  - `test` (boolean)
    Example: true

## Response 201 fields (application/json):

  - `aes_itn` (string)
    required if eel_pfc is AES_ITN
AES / ITN reference of the shipment.

  - `b13a_filing_option` (string)
    B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). 
 More information on reporting commercial exports from Canada. 
Allowed values available here
    Example: "FILED_ELECTRONICALLY"

  - `b13a_number` (string)
    must be provided if and only if b13a_filing_option is provided
Represents: the Proof of Report (POR) Number when b13a_filing_option is FILED_ELECTRONICALLY; 
the Summary ID Number when b13a_filing_option is SUMMARY_REPORTING; 
or the Exemption Number when b13a_filing_option is NOT_REQUIRED.

  - `certificate` (string)
    Certificate reference of the shipment.

  - `certify` (boolean, required)
    Expresses that the certify_signer has provided all information of this customs declaration truthfully.
    Example: true

  - `certify_signer` (string, required)
    Name of the person who created the customs declaration and is responsible for the validity of all 
information provided.
    Example: "Shawn Ippotle"

  - `commercial_invoice` (boolean)

  - `contents_explanation` (string)
    required if contents_type is OTHER
Explanation of the type of goods of the shipment.
    Example: "T-Shirt purchase"

  - `disclaimer` (string)
    Disclaimer for the shipment and customs information that have been provided.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Max 554 characters |

  - `duties_payor` (object)
    Specifies who will pay the duties for the shipment. Only accepted for FedEx shipments.

  - `duties_payor.account` (string)
    Account number to be billed for duties.
    Example: "2323434543"

  - `duties_payor.type` (any)
    Party to be billed for duties.
    Enum: "SENDER", "RECIPIENT", "THIRD_PARTY"

  - `duties_payor.address` (object)

  - `duties_payor.address.name` (string)
    Name of the party to be billed for duties.
    Example: "Patrick Kavanagh"

  - `duties_payor.address.zip` (string)
    Postal code of the party to be billed for duties.
    Example: "80331"

  - `duties_payor.address.country` (string)
    Country ISO code of account number to be billed.
    Example: "DE"

  - `exporter_identification` (object)
    Additional exporter identification that may be required to ship in certain countries

  - `exporter_identification.eori_number` (string)
    Economic Operators' Registration and Identification (EORI) number. Must start with a 2 character 
country code followed by a 6-17 character alphanumeric identifier (e.g. PL1234567890ABCDE).
More information on EORI.
    Example: "PL123456790ABCDE"

  - `exporter_identification.tax_id` (object)
    Tax identification that may be required to ship in certain countries. Typically used to assess duties on 
goods that are crossing a border.

  - `exporter_identification.tax_id.number` (string)
    Tax identification number.
    Example: "123456789"

  - `exporter_identification.tax_id.type` (any)
    Type of tax identification.
* EIN - Employer Identification Number, also known as a Federal Tax Identification Number.
* VAT - Value Added Tax identification number.
* IOSS - Import One-Stop Shop
* ARN - Australian Taxation Office Reference Number
    Enum: "EIN", "VAT", "IOSS", "ARN"

  - `exporter_reference` (string)
    Exporter reference of an export shipment.

  - `importer_reference` (string)
    Importer reference of an import shipment.

  - `is_vat_collected` (boolean)
    Indicates whether the shipment's destination VAT has been collected. May be required for some destinations.

  - `invoice` (string)
    Invoice reference of the shipment.
    Example: "#123123"

  - `license` (string)
    License reference of the shipment.

  - `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 #123123"

  - `notes` (string)
    Additional notes to be included in the customs declaration.

  - `address_importer` (string)
    Object ID of the Importer address.
    Example: "257ba08436604d2aaf069caafe7acb2a"

  - `contents_type` (string, required)
    Type of goods of the shipment.  
Allowed values available here

  - `eel_pfc` (string)
    EEL / PFC type of the shipment. For most shipments from the US to CA, NOEEI_30_36 is applicable; for most 
other shipments from the US, NOEEI_30_37_a is applicable.
Allowed values available here

  - `incoterm` (string)
    The incoterm reference of the shipment. FCA is available for DHL Express and FedEx only.
eDAP is available for DPD UK only. DAP is available for DHL Express, FedEx, and DPD UK.
If expecting DAP for other carriers, please use DDU.
Allowed values available here
Carrier-specific restrictions are in the table below.

Carrier-Specific Constraints:
| Carrier | Constraints |
|:---|:---|
| FedEx | Must be one of DDP, DDU, FCA, DAP |

  - `invoiced_charges` (object)
    Additional invoiced charges to be shown on the Customs Declaration Commercial Invoice.

  - `invoiced_charges.currency` (string, required)
    Currency for the invoiced charges amounts incurred on the end consumer.

  - `invoiced_charges.total_shipping` (string)
    Total shipping paid by the buyer.

  - `invoiced_charges.total_taxes` (string)
    Total taxes paid by the buyer.

  - `invoiced_charges.total_duties` (string)
    Total duties paid by the buyer.

  - `invoiced_charges.other_fees` (string)
    Other fees paid by the buyer.

  - `items` (array, required)
    Distinct Parcel content items as Customs Items object_ids.
    Example: ["5087f181d1dc4b14b73fdbf636498886"]

  - `non_delivery_option` (string, required)
    Indicates how the carrier should proceed in case the shipment can't be delivered.
Allowed values available here

  - `object_created` (string)
    Date and time of object creation.
    Example: "2014-07-17T01:01:08.306Z"

  - `object_id` (string)
    Unique identifier of the given object.
    Example: "e2197a54da9d470480f4f8796cc419cb"

  - `object_owner` (string)
    Username of the user who created the object.
    Example: "shippotle@shippo.com"

  - `object_state` (string)
    Indicates the validity of the enclosing object
    Enum: "VALID", "INVALID"

  - `object_updated` (string)
    Date and time of last object update.
    Example: "2014-07-17T01:01:08.306Z"

  - `test` (boolean)
    Indicates whether the object has been created in test mode.
    Example: true