Migration to general_customs_declaration

The top-level customs_declaration object in requests to create or update shipments (e.g., in CreateCompositeShipmentRequest) previously supported several specific, now-deprecated declaration types. These have now been replaced with a general customs declaration that can be used for all occasions.

Summary of Changes

• Deprecated JSON fields on CustomsDeclaration:
  • cn22
  • cn23
  • cp72
  • electronic_invoice_ups
  • electronic_invoice_fedex
• Replacement: All of the above are replaced by the general_customs_declaration field which uses the GeneralCustomsDeclaration object.
• Affected Endpoints:
  • POST /shipments.create
  • POST /shipments.createAndBook
  • POST /customs_declaration.upsert
  • All endpoints responding with a Shipment object (as customs.declaration will now contain general_customs_declaration instead of the deprecated fields).

Reason for Deprecation

Previously, the customs_declaration object supported several distinct, specific declaration types (e.g., cn22, electronic_invoice_ups). This approach led to a fragmented and less flexible system, requiring integrators to manage multiple structures for similar information. To simplify the API, improve maintainability, and allow for a more consistent representation of customs data, these specific types have been consolidated into a single, general customs declaration (general_customs_declaration). This new structure is designed to be comprehensive enough for all use cases, reducing complexity and making future extensions easier.

Before Migration (Example JSON Body)

You might have been sending a customs_declaration object in your request body like this:

{
  "customs_declaration": {
    "cn22": {
      "items": [
        {
          "description": "Cotton T-Shirt",
          "quantity": 2,
          "total_net_weight": 400,
          "total_value": 5000,
          "hs_tariff_number": "61091000",
          "country_of_origin": "PT"
        }
      ],
      "currency": "USD",
      "total_gross_weight": 550,
      "contents_type": "SALE",
      "eori_number": "SE1234567890"
    }
  }
}

After Migration (Example JSON Body)

The equivalent object using general_customs_declaration is structured as follows. Note that the entire customs_declaration object is now replaced by the content of GeneralCustomsDeclaration.

{
  "customs_declaration": {
    "general_customs_declaration": {
      "items": [
        {
          "name": "Cotton T-Shirt",
          "quantity": 2,
          "unit_net_weight": 200,
          "unit_value": 2500,
          "hs_tariff_number": "61091000",
          "country_of_origin": "PT"
        }
      ],
      "currency": "USD",
      "total_gross_weight": 550,
      "contents_type": "SALE",
      "seller_identification_numbers": {
        "eori": "SE1234567890"
      }
    }
  }
}

Migration Steps

To migrate your integrations, you will need to:

1. Identify Existing Declaration Type: Determine which of the deprecated customs declaration types (cn22, cn23, cp72, electronic_invoice_ups, electronic_invoice_fedex) your integration is currently using.
2. Map Fields to GeneralCustomsDeclaration: Using the provided field mapping tables, translate your existing customs data to the corresponding fields within the general_customs_declaration object.
3. Recalculate Item Values (Crucial): For each item within the customs declaration's items array, you must convert total_value to unit_value (total value / quantity) and total_net_weight to unit_net_weight (total net weight / quantity). This is a critical change, and failing to perform this calculation will result in incorrect customs declarations.
4. Update Request Bodies: Modify your POST /shipments.create, POST /shipments.createAndBook, or POST /customs_declaration.upsert request bodies to use the new general_customs_declaration object instead of the deprecated specific types. Ensure the entire customs_declaration object now contains only the general_customs_declaration field.
5. Update API Response Parsing: When consuming API responses that include shipment details, ensure your code is updated to expect and parse the customs.declaration field to contain general_customs_declaration instead of the old specific types.

Field Mapping Tables

DeclarationCN (CN22, CN23, CP72)

cn22, cn23, cp72 have been moved to general_customs_declaration and the fields should be mapped as:

ElectronicInvoiceUPS / ElectronicInvoiceFedex

electronic_invoice_ups and electronic_invoice_fedex have been moved to general_customs_declaration and the fields should be mapped as: