ups_error_120317

[yakuza916-star]

UPS REST API v2403 — Error 120317 when creating Import Control shipment (importer controls inbound pickup)

Business scenario

We are an importer in Poland. We order goods from suppliers in other EU countries (e.g. Italy). We want to control the inbound shipment using our Polish UPS account — we generate the label, send it to the supplier, and the courier picks up the package at the supplier's location. We pay for the transport.

This is the standard UPS Import Control use case:

• We are the importer/receiver (Poland) — we hold the UPS account, generate the label, pay for transport
• Our supplier is the physical sender (Italy) — they hand over the package when the courier arrives
• ShipFrom = supplier's address (Italy, IT)
• ShipTo = our address (Poland, PL)
• Shipper = us as the controlling importer (Poland, PL) with our UPS account number

Our UPS account has Import Control activated — the same shipment works correctly on ups.com via the Import Control tab. The generated label shows the Italian supplier as the FROM address and our account as "BILLING: I/C RECEIVER".

Problem

When we try to replicate this via REST API v2403, we get error 120317:

"ShipFrom address country code does not match Shipper address country code"

Endpoint

POST https://onlinetools.ups.com/api/shipments/v2403/ship

What we tried

Attempt 1 — Shipper = Italian supplier (no ShipperNumber) + BillThirdParty with our importer account
→ Error 120100: "Missing or invalid shipper number"

Attempt 2 — Shipper = us/importer (PL, with ShipperNumber) + ShipFrom = supplier (IT) + ImportControlIndicator: "" at Shipment level
→ Error 120317

Attempt 3 — Shipper = us/importer (PL, with ShipperNumber) + ShipFrom = supplier (IT) + ShipmentServiceOptions.ImportControl.Code: "01"
→ Error 120317

Payload (Attempt 3)

{
  "ShipmentRequest": {
    "Request": {
      "RequestOption": "nonvalidate",
      "SubVersion": "1801"
    },
    "Shipment": {
      "Shipper": {
        "Name": "Importer Company Name",
        "ShipperNumber": "XXXXXXX",
        "Address": {
          "AddressLine": ["Importer Street 1"],
          "City": "Importer City",
          "PostalCode": "00-000",
          "CountryCode": "PL"
        }
      },
      "ShipFrom": {
        "Name": "Supplier Company Name",
        "Address": {
          "AddressLine": ["Supplier Street 1"],
          "City": "Supplier City",
          "PostalCode": "00000",
          "CountryCode": "IT"
        }
      },
      "ShipTo": {
        "Name": "Importer Company Name",
        "Address": {
          "AddressLine": ["Importer Street 1"],
          "City": "Importer City",
          "PostalCode": "00-000",
          "CountryCode": "PL"
        }
      },
      "PaymentInformation": {
        "ShipmentCharge": {
          "Type": "01",
          "BillShipper": { "AccountNumber": "XXXXXXX" }
        }
      },
      "Service": { "Code": "11" },
      "ShipmentServiceOptions": {
        "ImportControl": {
          "Code": "01",
          "Description": "Electronic Import Control"
        }
      },
      "Package": [{
        "PackagingType": { "Code": "02" },
        "PackageWeight": {
          "UnitOfMeasurement": { "Code": "KGS" },
          "Weight": "11"
        }
      }]
    }
  }
}

Response

{
  "response": {
    "errors": [{
      "code": "120317",
      "message": "ShipFrom address country code does not match Shipper address country code"
    }]
  }
}

Additional findings

We discovered that error 120317 is only triggered when ShipmentCharge.Type = "01" (Transportation) is present. When we use Type = "02" (Duties/Taxes) with BillReceiver, the 120317 validation is bypassed — but then UPS returns:

Error 9120082: "The payer of Transportation charges is required."

This creates a dead loop:

• Type "01" (Transportation) + BillShipper → 120317 (ShipFrom ≠ Shipper country)
• Type "01" (Transportation) + BillReceiver → 9120000 (internal server error instead of proper validation)
• Type "01" (Transportation) + BillThirdParty (same account as Shipper) → 120412 ("Third Party account cannot be same as Shipper Number")
• Type "02" (Duties) + BillReceiver → 9120082 (transportation payer missing)
• Both Type "01" + Type "02" as array + BillReceiver → 120317
• Type "02" + ShipmentServiceOptions.ImportControl.Code: "01" → 9120082

The REST API v2403 returns error 9120000 ("Ship web service is currently unavailable") for BillReceiver + cross-country ShipFrom/Shipper — this is an internal API crash rather than a proper validation error. The same configuration via UPS.com Import Control tab generates labels correctly with "BILLING: I/C RECEIVER 81081V" on the label.

Complete billing matrix for Shipper=PL, ShipFrom=IT, ShipTo=PL:

Payment Type	Result
BillShipper (account XXXXXXX)	120317 — ShipFrom ≠ Shipper country
BillReceiver (account XXXXXXX, PostalCode PL)	9120000 — internal server error
BillThirdParty (account XXXXXXX)	120412 — third party = shipper not allowed

Question

What is the correct REST API v2403 payload structure for a standard Import Control shipment where:

• The importer (destination country, PL) holds the UPS account, generates the label and pays for transport
• The supplier (origin country, IT) is the physical pickup location
• The importer's account is used for billing

The same configuration works on ups.com via the Import Control tab — so the account has the feature enabled. Why does the API return 120317 for Transportation charges with cross-country ShipFrom/Shipper, and how should the payload be structured?

Does the API application require a separate Import Control activation in the UPS Developer Portal, independent of the account-level activation?