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” | The ID of the related existing shipment, which was provided by Seven Senders when shipment was created. |
order_id | m | string | “MM12345” | The ID of the related existing order. |
invoice_id | m | string | “11223344” | The ID of the invoice that was issued to the recipient for the order. |
invoice_date | m | datetime | "2022-08-01T10:10:10.933Z" | The date of the invoice. |
incoterm | m | string | “DDP” | The incoterm under which the shipment is sold (e.g. in GB will be DAP). |
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. |
planned_pickup_datetime | m | datetime | "2022-08-01T10:10:10.933Z" | The date and time agreed with the carrier to pick up the shipment at your warehouse. |
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 or UID). |
arrival_country_customs_id | m | string | “CHE372842991” | The identification number of the legal entity sending the shipment in the arrival country (EORI or UID). |
net_weight | m | number | 230 | The net weight of the shipment (articles and their primary packaging). |
gross_weight | m | number | 321.5 | The gross weight of the shipment (articles and their primary packaging plus the secondary packaging). |
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 | “EUR” | ISO currency code in which the value of the merchandise was declared (Transaction currency in which the client performs the payment.) |
consignment_id | o | string | “123456” | The Seven Senders ID of the consignment on which this shipment will be transported. |
packaging | o | string | “Paperboard Box” | 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. |
parent_container | o | string | “123456789” | The unique id of the dispatch unit on which the shipment is placed (e.g. pallet barcode. This id is not same as the consignment id). |
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. |
last_name | m | string | “Mustermann” | Recipient last name. |
address | m | string | “Berlinerstr. 4” | Recipient address. |
city | m | string | “Basel” | Recipient city. |
zip | m | string | “4001” | Recipient zip. |
country | m | string | “CH” | Recipient country in ISO2 format. |
company_name | o | string | “Seven Senders” | Recipient company name. |
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. |
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. |
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. |
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). |
preferential_code | m | integer | 1 | Customs code indicating duty preference type (1 = preferential goods or 2 = non preferential goods). |
departure_country_ tariff_number | m | string | “61091000” | Harmonized Tariff / Commodity code of the article according to the legislation in the departure country. |
arrival_country_ description | m | string | “T-Shirt gewirkt aus Baumwolle” | Description of the article in the official language of the arrival country. |
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). |
arrival_country_ tariff_number | m | string | “61091000” | Harmonized Tariff / Commodity code of the article according to the legislation in the arrival country. |
qty | m | integer | 2 | Quantity of the article. |
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_u | 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 | string | 39.95 | Monetary value of an individual article without VAT. Conditional rule 2. |
total_net_value | c | string | 79.90 | Total monetary value of all articles without VAT (with the same UPC Code). Conditional rule 2. |
sales_value | c | string | 142.62 | Monetary value of an individual article including VAT. Conditional rule 3. |
sales_value_total | c | string | 47.54 | Total monetary value of all articles including VAT (with the same UPC Code). 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. |
vat_tariff | o | string | 19 | The percentage of related VAT tariff. |
article_id | o | string | “9988776655” | Your internal reference for an article. |
url | o | string | “https://www.bergfreunde.de/
patagonia-womens-regenerative-organic-cotton-tee-t-shirt/” | The product page URL. |
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. |
language_code | o | string | “de” | The ISO 693-1 language in which the product page is. |
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
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.
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.
Related article: Customs Manifest