1.4. Create Customs Shipment

TABLE OF CONTENTS

Customs Shipment endpoint
Precondition
POST Customs Shipment Parameters
GET Customs Shipment
PUT Customs Shipment
DELETE Customs Shipment

Customs Shipment endpoint

A shipment resource represents a physical parcel with carrier information and recipient address. The shipment contains one or multiple articles (SKU - stock keeping units).

Precondition

The order, shipment and label (if applicable) is previously created using the existing Single API endpoints: POST Orders, POST Shipments or POST Labels.

POST Customs Shipment Parameters

With POST Customs Shipment method, you can submit customs data for your shipment. This method does not create shipments in analytics. You will need first to create the shipment with the POST shipments method and then submit the customs data with this endpoint.

Parameter	M/O	Type	Example	Description
shipment_id	m	string	“5857965”	We accept only shipment_id for which we have delivery data (previously created via the POST Label or Shipment endpoint) and are not previously posted in this endpoint.
order_id	m	string	“MM12345”	We accept only order_id's for which we have delivery data (previously created via POST Label, Shipment or Order endpoint) A check is performed that the shipment_id belongs to this order_id.
invoice_id	o	string	“11223344”	The ID of the invoice that was issued to the recipient of the order. The invoice_id must be unique per order. Within one order, you can have many unique id's. A check is performed by the system to ensure unicity.
invoice_date	o	datetime	"2022-08-01T10:10:10.933Z"	The date of the invoice that was issued to the recipient of the order. Date time, including time zone, date (no time), date time (no timezone). IN the case of the latter 2 we will default the time and timezone to UTC.
incoterm	m	string	“DDP”	The incoterm under which the shipment is sold. Please inform Seven Senders about the used incoterm on your shipments.
tracking_code	m	string	“996013560100004”	The unique outbound shipment track and trace code given by the carrier.
return_tracking_code	o	string	“06275013959708”	The unique return shipment track and trace code given by the carrier. This is an optional field, it might be helpful for Seven Senders to be provided in case the return label was produced and packed inside the parcel. If is_return = TRUE, then the tracking code of the return parcel needs to be populated in the field tracking_code.
planned_pickup_datetime	o	datetime	"2022-08-01T10:10:10.933Z"	The date and time agreed with the carrier to pick up the shipment at your warehouse. Date time, including time zone, date (no time), date time (no timezone). In the case of the latter 2 we will default the time and timezone to UTC. If not sent in the request, we will default it with the shipment created at.
departure_country	m	string	“DE”	The departure country in ISO2 format. Remark: This is not the country of origin of the shipment.
departure_country_customs_id	m	string	“DE123456789123456”	The identification number of the legal entity sending the shipment in the departure country (EORI, UID or NUF/VOEC). EORI number for the shipments departing from or arriving to EU or GB (in case of departure or arriving within EU, you can use any EU country EORI number. Example: NL EORI Number for the shipments departing from DE). The EORI number is not same as VAT Number. UID number for the shipments departing from or arriving to CH. NUF/VOEC number for shipments departing from or arriving to NO. In case the EORI number is not issued during the integration tests, please use: DE123456789123456.
arrival_country_customs_id	m	string	“CHE123456789”	The identification number of the legal entity sending the shipment in the arrival country (EORI, UID or NUF/VOEC). In case the EORI/UID/NUF/VOEC number is not issued during the integration tests, please use: GB123456789000, CHE123456789000 or NUF123456789000.
net_weight	m	number	230	The net weight of the shipment (refers to articles and their primary packaging). The sum of SKU total_net_weight should be equal to the shipment net_weight.
gross_weight	m	number	321.5	The gross weight of the shipment (articles and their primary packaging plus the secondary packaging). The gross weight must be higher then the shipment net_weight.
weight_um	m	string	“G”	The unit of the weight(s) you are submitting for the shipment: K = kilos, G = grams, L = pounds, O = ounces.
departure_country_currency	m	string	“CHF”	ISO currency code in which the value of the merchandise was declared (Transaction currency in which the recipient performs the payment. For example: If the shipment is DE - CH and the recipient paid in CHF then the currency provided here is CHF). Important is that all shipment on the same manifest must be declared in the same currency.
consignment_id	o	string	“123456”	The Seven Senders ID of the consignment on which this shipment will be transported. This is an optional field, it might be helpful for Seven Senders to be provided. if not known, please leave it empty.
packaging	o	string	“PK”	Type (description) of the shipment secondary packaging. Recommended is to use: PK for package or PX for pallet.
reference_number	o	string	“ref12345”	The unique reference number that represents an internal shipment reference in your system.
is_return	o	boolean	false	Indicates whether the shipment is a return from the recipient. For customers that are doing outbound with Seven Senders, the customer does not need to create return customs shipment. Only for customers that only do returns, we need a return customs shipment. If the shipment is outbound then this field is false. If the shipment is return then this field is true.
parent_container	o	string	“123456789”	The unique id of the dispatch unit on which the shipment is placed (e.g. the barcode on the pallet label). This id is not same as the consignment id. This is an optional field, but its highly recommended to provide it especially if the manifest has more than 1 pallet. This information helps to find the parcel easily when the customs authorities require inspection.
arrival_country_currency	o	string	“CHF”	ISO currency code of the arrival country of the shipment.
Recipient object
first_name	m	string	“Max”	Recipient first name. In case of B2C this must be a private person and cannot be company name.
last_name	m	string	“Mustermann”	Recipient last name. In case of B2C this must e a private person and cannot be company name.
address	m	string	“Berlinerstr. 4”	Recipient address.
city	m	string	“Basel”	Recipient city. Important is that the city exists and that is in the destination country. Limit of max 35 characters.
zip	m	string	“4001”	Recipient zip. Important is that the zip exists and that is in the destination country. For GB shipments the letters should be capitalized.
country	m	string	“CH”	Recipient country in ISO2 format.
company_name	o	string	“Seven Senders”	Recipient company name. In case of B2B and the recipient wants to send a parcel to its company address then the company name can be put in here.
address_details	o	string	“5th floor”	Recipient additional address details that might be helpful to deliver.
phone	o	string	“+490000000001”	Recipient phone number.
email	o	string	“m.max@example.com”	Recipient email address. Recommendation: In case there are errors with first/last name, it is good to have the email in order for 7S Customs to identify the first and last name.
SKU (stock keeping unit - article) object as array
id	m	number	1	An id of the SKU object. The value must be a unique number per shipment. Maximum 11 digits, no leading 0, no decimal places. Article Bundles: When an article bundle is sold in the shipment, then each article needs to be a separate SKU.
country_of_origin	m	string	“IN”	ISO-2 country code for the country of origin of the article (where it was produced).
departure_country_description	m	string	“T-Shirt gewirkt aus baumwolle”	Description of the article in the official language of the departure country. This must be a customs valid description - commercial product description. The description must include (1) article, (2) material, (3) what is the article used for, (4) product name. Good example is: Pullover out of cotton knitted for women Marc O'Polo.
language_departure_ country_description	m	string	“de”	The ISO 693-1 code of the official language of the departure country (the language in which the article description is provided). The language code must be provided in sentence case letters.
preferential_code	m	string	"1"	Customs code indicating duty preference type (1 = preferential goods or 2 = non preferential goods). Preferential goods are goods that are produced in the EU, where the majority of materials originate from the EU. If customers declare preferential goods, they must have a preferential calculation in place. Please note that most customers do not have this calculation in place.
departure_country_ tariff_number	m	string	“61091000”	Harmonized Tariff / Commodity code of the article according to the legislation in the departure country. For shipments departing from EU, CH or arriving to CH the code is 8 digits.
arrival_country_ description	m	string	“T-Shirt gewirkt aus Baumwolle”	Description of the article in the official language of the arrival country. The description must include (1) article, (2) material, (3) what is the article used for, (4) product name. Good example is: Pullover out of cotton knitted for women Marc O'Polo.
language_arrival_ country_description	m	string	“de”	The ISO 693-1 code of the official language of the arrival country (the language in which the article description is provided). The language code must be provided in sentence case letters.
arrival_country_ tariff_number	m	string	“61091000”	Harmonized Tariff / Commodity code of the article according to the legislation in the arrival country. For shipments arriving in DE the code is 11 digits, arriving to EU, UK the code is 10 digits, arriving to CH the code is 8 digits, arriving to NO is 8 digits.
qty	m	integer	2	Quantity of the articles of this sku_id.
qty_um	o	string	““	Special unit of measurement of the article. List of expected codes: link
weight	c	number	115	Weight of an individual article with accuracy to 3 decimal places. Conditional rule 1.
total_net_weight	c	number	230	Total weight of the articles with accuracy to 3 decimal places (with the same UPC Code). Conditional rule 1.
weight_um	m	string	“G“	The unit of the weight(s) you are submitting for the article: K = kilos, G = grams, L = pounds, O = ounces.
net_value	c	number	39.95	Monetary value of an individual article without VAT. Gifts: The production value must be stated for goods provided free of charge. For gifts we recommend stating the value that would be used when the article is sold. Article bundles: If the article values under the bundle have higher value than the recipient has paid, then a discount needs to be applied. The value of the individual articles under the bundle must always add up to a value that is also shown on the invoice that the recipient received. Discounts: Discounts must be substracted from the item price - e.g.,10% or 15 EUR voucher. In the case of multiple items, the discount must be distributed proportionally. Conditional rule 2.
total_net_value	c	number	79.90	Total monetary value of all articles without VAT (with the same UPC Code). Gifts: The production value must be stated for goods provided free of charge. For gifts we recommend stating the value that would be used when the article is sold. Article bundles: If the article values under the bundle have higher value than the recipient has paid, then a discount needs to be applied. The value of the individual articles under the bundle must always add up to a value that is also shown on the invoice that the recipient received. Discounts: Discounts must be substracted from the item price - e.g.,10% or 15 EUR voucher. In the case of multiple items, the discount must be distributed proportionally. Conditional rule 2.
sales_value	c	number	43.026	Monetary value of an individual article including VAT. Gifts: The production value must be stated for goods provided free of charge. For gifts we recommend stating the value that would be used when the article is sold. Article bundles: If the article values under the bundle value have higher value than the recipient has paid, then a discount needs to be applied. The value of the individual articles under the bundle must always add up to a value that is also shown on the invoice that the recipient received. Discounts: Discounts must be substracted from the item price - e.g,10% or 15 EUR voucher. In the case of multiple items, the discount must be distributed proportionally. Conditional rule 3.
sales_value_total	c	number	86.052	Total monetary value of all articles including VAT (with the same UPC Code). Gifts: The production value must be stated for goods provided free of charge. For gifts we recommend stating the value that would be used when the article is sold. Article bundles: If the article values under the bundle have higher value than the recipient has paid, then a discount needs to be applied. The value of the individual articles under the bundle must always add up to a value that is shown on the invoice that the recipient received. Discounts: Discounts must be substracted from the item price - e.g,10% or 15 EUR voucher. In the case of multiple items, the discount must be distributed proportionally. Conditional rule 3.
upc_code	m	string	“116800711680”	The UPC code of the article (Universal Product Code). This value must be present on the article and preferably scannable. Every variation of your product will need its own UPC/EAN.
vat_tariff	o	string	"8.1"	The percentage of related VAT tariff in the arrival country. We strongly recommend to provide this value for shipments to CH so that the customs procedures and duty definition is eased up.
article_id	o	string	“9988776655”	Customer internal reference for an article. Highly recommended to be provided as this field might be changed to mandatory in the near future.
url	o	string	“https://www.bergfreunde.de/ patagonia-womens-regenerative-organic-cotton-tee-t-shirt/”	The product page URL. Urls with words in "" are not accepted as valid by our API.
brand	o	string	“Patagonia”	The brand of the article.
color	o	string	“Plum grey”	The color of the article.
category	o	string	“Outdoor Bekleidung/Shirts, Hemden & Longsleeves/T-Shirts.”	The category keywords of the article to narrow down the selection.
image_url	o	string	“https://www.bergfreunde.de/ patagonia-womens-regenerative-organic-cotton-tee-t-shirt/#galleryid-1.pictureid-1”	The image URL. Urls with words in "" are not accepted as valid by our API.
language_code	o	string	“de”	The ISO 693-1 language in which the product page is. The language code must be provided in sentence case letters.
waiver_reference	o	string	"DE-ÖKO-001"	Waiver reference.

Agenda: m = mandatory, o = optional, c = conditional, below is the description field for the rule.

Condition rule:

either the weight or total_net_weight fields can be provided. If providing the weight field, we will multiply it by the SKU qty field to determine the total weight for that particular article/SKU.
either the net_value or total_net_value fields can be provided. If providing the net_value field, we will multiply it by the SKU qty field to determine the total value for that particular article/SKU.
either the sales_value or sales_value_total fields can be provided. If providing the sales_value field we will multiply it by the SKU qty field to determine the total value for that particular article/SKU.

The customer will need to provide single article/SKU values (weight, net_value, sales_value ) or total values (total_net_weight, total_net_value, sales_value_total ) for this three block of fields.

net_value and total_net_value are mandatory if: recipient.country = GB or recipient.country = CH, DE, FR, BE, LU, NL, PL, PT, ES and incoterm = DAP.
sales_value and sales_value_total are mandatory if: recipient.country = CH, DE, FR, BE, LU, NL, PL, PT, ES and incoterm is different then DAP.

GET Customs Shipment/s

With GET Customs Shipment method, you can retrieve single or multiple shipments that have previously been created. This endpoint offers to filter shipments based on shipment_id or/and shipment_tracking_code.

With GET Customs Shipments method, you can retrieve single or multiple shipments that have been previously created. The endpoint offers to filter shipments based on manifest_id, shipment_id, planned_pickup_date, order_id, types, return_inspected, status, return_processed_date [before], return_processed_date [after].

The GET Shipments endpoint has default page 1 and 50 as itemsPerPage. The endpoint can support maximum of 500 itemsPerPage. If exceeded we will default to 500.

Details about the inspected return or undeliverable shipments via this endpoint can be found here: link.

PUT Customs Shipment

With PUT Customs Shipment method, you can update any field of a previously created shipment by shipment_id. In case an SKU object needs to be updated then the id (of the sku used during the creation of the shipment) must to be provided. Updating shipment is possible if this shipment was not declared in a customs manifest. If the shipment was declared in a customs manifest, and needs to be updated, then please reach out to your Seven Senders contact as quickly as possible.

DELETE Customs Shipment

With DELETE Customs Shipment method, you can delete a previously created shipment by providing shipment_id. Deleting shipment is possible if this shipment was not declared in a customs manifest. If the shipment was declared in a customs manifest, and needs to be deleted, then please reach out to your Seven Senders contact as quickly as possible.