UPS Customs Detail (Trade Compliance)

Some trade lanes require regulatory data beyond the commercial invoice — for example FDA product data on US imports, CSB details on India exports, an MRN on Germany exports, or Section 232 metal content on US imports. UPS collects these through its Customs Detail API (/api/trade/compliance/v2/content/fields/customs-detail), which returns the current compliance fields for a lane so new country rules never require a code change.

Available since version 2.8.2.369 on the UPS REST carrier (ups-rest) via the customsdetail action. The request_option param selects the sub-operation:

Looking up required fields#

Filter the lookup with any of: to_country (import country), ship_country (export country), commodity codes from your customs lines, customs_content_type (Gift, Commercial, Sale, Sample, Repair, Return, Other), weight/weight_unit (LBS/KGS), customs_value and currency, user_roles (Importer/Exporter), commerce_model (B2B, B2C, C2B, C2C), and locale. Omitting a country returns all fields for all countries.

{
  "carrier": "ups-rest",
  "action": "customsdetail",
  "params": {
    "request_option": "fields",
    "to_country": "US",
    "ship_country": "IT",
    "customs_content_type": "Commercial",
    "commerce_model": "B2B",
    "user_roles": ["Importer"],
    "customs": [
      { "customs_hs_tariff": "3003395000" }
    ]
  }
}

The response contains commodity_codes (which regulations apply to each commodity, "All" meaning every product line) and field_groups. Each group carries a group_key (e.g. US-IMP-FDA), the regulation and its sections, group-level validation_rules, and a fields array describing each field to capture: field_key (the identifier to send back), label, tooltip, is_required (Y, N, or C with requirement_conditions), display_conditions, field_type (textbox, list, date, radio, checkbox, textarea), level (Shipment or Product), and a validation object (data type, min/max length, regex, allowed list values).

Validating and saving field values#

Send values back grouped under the group_key and field_key identifiers from the lookup. Shipment-level values go in the top-level customs_metadata param; product-level values go in customs_metadata on the matching customs line. request_option: "validate" checks the values only; request_option: "save" also submits them for merging into the shipment and requires the shipment's lead tracking_number (so it runs after submitshipment).

{
  "carrier": "ups-rest",
  "action": "customsdetail",
  "params": {
    "request_option": "save",
    "account_number": "your-ups-account-number",
    "tracking_number": "1Z1443YY0161231327",
    "to_country": "US",
    "ship_country": "IN",
    "customs_content_type": "Commercial",
    "customs_metadata": [
      {
        "group_key": "IN-EXP-CSB",
        "fields": [
          { "field_key": "CSBType", "field_value": "3" },
          { "field_key": "IECCode", "field_value": "1234567890" }
        ]
      }
    ],
    "customs": [
      {
        "invoice_line_part_number": "PART-001",
        "customs_description": "Medical device",
        "commodity_code": "3821000010",
        "customs_metadata": [
          {
            "group_key": "US-IMP-FDA",
            "fields": [
              { "field_key": "MnuNa", "field_value": "UPS Labs" },
              { "field_key": "MnuCtyNa", "field_value": "Atlanta" }
            ]
          }
        ]
      }
    ]
  }
}

Customs lines with a customs_metadata array are sent as products; invoice_line_part_number becomes the product ID and should match the part number used on the commercial invoice so UPS can associate the data with the right invoice line. Lines without customs_metadata are skipped. A field may also carry regulation_sections copied from the lookup response when a value applies only to specific regulation sections.

On success UPS returns no body and RocketShipIt responds with "success": true; validation failures come back in errors with the failing field and value. Optional params: invoice_form_group_id (form group ID of the generated invoice), weight/weight_unit, customs_value/currency, user_roles, and commerce_model.

See full requests in the API Explorer or on the examples site: Required Fields, Validate, Save.

Note: the EU de minimis product identifiers are a different UPS mechanism — they ride on the shipment request itself. See EU De Minimis.