When shipping from the EU to a non-EU country, or vice versa, it is mandatory to include customs details for certain carriers. Some carriers offer paperless invoicing services, also known as electronic invoicing. This article will explain how to include this information in your request to nShift's Shipment Server API.

• Example requests to Shipment Server API
• Multiple customs detail lines
• Overview of Details fields

Example request to Shipment Server API

Please be aware that carriers have different requirements for the custom details so even though many of the fields are similar, they will vary from carrier to carrier. 

The request example below shows a shipment with carrier UPS using the product "UPS Saver" and the service "Commercial invoice (Paperless)". The sender is located in Denmark and the receiver is in the United States.

GroupID 1 refers to the group of fields known as Article Info and contains customs information related to the individual items. Here it is possible to add information on detail line level.

GroupID 2 refers to the group of fields known as Customs Info and contains general customs information related to the shipment. 

See our appendix to get a list of all possible GroupIDs. 

The Kind IDs in each group refer to the individual customs fields, e.g. kindID 7 in group 1 refers to the description of the goods. See the table with all possible Detail Kind IDs at the bottom of the article. The table also gives you an overview of supported detail fields on the most used carriers supporting customs details. Not all the fields are mandatory on each carrier. You may use the method ValidateShipment to see if you have filled in the minimum required fields in your request.

{
  "Kind": 1,
  "OrderNo": "12345",
  "ActorCSID": 1378,
  "ProdConceptID": 677,
  "Addresses": [
    {
      "Kind": 2,
      "Name1": "nshift",
      "Street1": "Runevej 2A",
      "PostCode": "8210",
      "City": "AARHUS V",
      "Phone": "70273377",
      "Attention": "Jane Doe",
      "CountryCode": "DK"
    },
    {
      "Kind": 1,
      "Name1": "Beverly Hills Hotel",
      "Street1": "9641 Sunset Blvd",
      "PostCode": "90210",
      "City": "Beverly Hills",
      "State": "CA",
      "Phone": "+13102762251",
      "Attention": "John Doe",
      "CountryCode": "US"
    }
  ],
  "Amounts": [
    {
      "Kind": 10,
      "CurrencyCode": "6",
      "Value": 18
    }
  ],
  "References": [
    {
      "Kind": 140,
      "Value": "test@test.com"
    },
    {
      "Kind": 108,
      "Value": "2025-02-24T13:14:13+0200"
    },
    {
      "Kind": 27,
      "Value": "John Doe"
    },
    {
      "Kind": 109,
      "Value": "2025-02-24T16:14:00"
    }
  ],
  "Lines": [
    {
      "GoodsTypeID": 1,
      "GoodsTypeName": "UPS Letter",
      "GoodsTypeKey1": "01",
      "GoodsTypeKey2": "02",
      "Number": 1,
      "RecycleTypeID": -1,
      "References": [
        {
          "Kind": 23,
          "Value": "Postcards"
        }
      ],
      "PkgWeight": 2000,
      "LineWeight": 2000
    }
  ],
  "Services": [
    60023
  ],
  "DetailGroups": [
    {
      "GroupID": 1,     //Article Info
      "Rows": [
        {
          "Details": [
            {
              "KindID": 193,     //goods line number
              "Value": 1     
            },
            {
              "KindID": 5,     //No units 
              "Value": "1"
            },
            {
              "KindID": 8,     //Unit of Measure (code)
              "Value": "KG"
            },
            {
              "KindID": 7,     //Description of goods
              "Value": "Commercial postcards"
            },
            {
              "KindID": 4,     //Country of Origin
              "Value": "DK"
            },
            {
              "KindID": 2,     //Unit Value
              "Value": "125"
            },
            {
              "KindID": 1,     //Article No
              "Value": "121212"
            },
            {
              "KindID": 18,    //Commodity code
              "Value": "48817300000"
            }
          ]
        }
      ]
    },
    {
      "GroupID": 2,     //Customs info
      "Details": [
        {
          "KindID": 19,     //Invoice number
          "Value": "12345678"
        },
        {
          "KindID": 24,     //Invoice date
          "Value": "20180924"
        },
        {
          "KindID": 21,     //Currency
          "Value": "DKK"
        },
        {
          "KindID": 20,     //Reason for Export
          "Value": "Other"
        }
      ]
    }
  ]
}

Multiple customs detail lines

If you have multiple detail lines on your shipment, you can include RowNo and LineNo in your request. RowNo specifies the detail line number related to a specific goods line, and LineNo specifies the goods line number.

The example below shows the structure of the DetailsGroups with 3 detail lines. The first two detail lines (Rows) are related to the first goods line, and the third detail line is related to the second goods line:

 "DetailGroups": [
        {
          "GroupID": 1,
          "GroupDisplayName": "Article Info",
          "Rows": [
            {
              "RowNo": 1, //detail line no 1 related to goodsline no 1
              "LineNo": 1, //goods line number 1
              "Details": [
                //all detail fields here...
              ]
            },
            {
              "RowNo": 2, //detail line no 2 also related to goodsline no 1
              "LineNo": 1, //goods line number 1
              "Details": [
                //all detail fields here...
              ]
            },
            {
              "RowNo": 1, //detail line no 1 related to goodsline no 2
              "LineNo": 2, //goods line number 2
              "Details": [
               //all detail fields here...
              ]
            }
          ]
        },
        {
          "GroupID": 2,
          "GroupDisplayName": "Customs Info",
          "Details": [
            //all detail fields here
          ]
        }
      ],

Overview of details fields

The table below shows all the Details fields. The names of the fields may vary from carrier to carrier, but the name in the API will always be the same. The fields with blue text are the most commonly used fields. The carrier columns show which fields are supported on the individual carriers.