UPS Interactive Description Guidance Virtual Sandbox

Guide international shippers through commodity classification to determine accurate HTS codes.

The Interactive Commodity Description API assists international shippers by providing a series of multiple-choice questions to improve commodity descriptions. This process helps map items to destination-specific Harmonized Tariff Schedule (HTS) codes, facilitating smoother customs clearance, reducing holds, and ensuring accurate assessment of duties and taxes.

Use this hosted sandbox to simulate UPS Interactive Description Guidance APIs without authentication, API keys, or extra dependencies. Point your code or SDK to the Beeceptor base URL, preferably through an environment variable or feature flag, and switch back to the production API when ready. This keeps your integration code consistent across local development, QA, demos, and production.

Use cases:

Use this sandbox to validate the interactive question-and-answer workflow, verify the mapping of natural language descriptions to HTS codes, test session management for multi-step classification, and handle feedback submission flows for customs compliance logic.

UPS Interactive Description Guidance virtual sandbox is up and running!

Use this sandbox URL as the API base in your code to simulate UPS Interactive Description Guidance responses instantly.

`https://ups-interactive-description.mock.beeceptor.com`

Interactive Description(3 operations)

POST

/interactive

Initiates an interactive description session for a product.

Header Name	Example
`transId`*	`"ut"`
`transactionSrc`*	`"irure"`

Request Payload

{
  "commodityCountryOfOrigin": "DE",
  "commodityCurrencyCode": "DJF",
  "commodityDescription": "Electronic Parts",
  "commodityHtsCode": "8471",
  "commodityQuantity": "500",
  "commodityUnitOfMeasure": "kg",
  "commodityValue": "1200.75",
  "exportCountryCode": "IN",
  "importCountryCode": "US",
  "locale": "de_DE",
  "shipperAccountNumber": "J5C2G4QPRF",
  "shipperName": "VonRueden LLC"
}

Response Payload

{
  "actualHts": "732393",
  "confidence": 0.73,
  "newProductDescription": "Plastic water storage containers",
  "noMoreQuestions": true,
  "questions": [
    {
      "assumed": false,
      "id": "0be4c933-13f9-486b-b67d-684b749fc5d2",
      "options": [
        "For decorative purposes",
        "For storing or drinking water"
      ],
      "other": [
        "PET",
        "PPT"
      ],
      "question": "What is the intended use?",
      "selected": 1,
      "type": "multiple_choice"
    },
    {
      "assumed": false,
      "id": "6f55165b-f9a3-4ac7-a33d-29bd9a0bcabe",
      "options": [
        "For decorative purposes",
        "For storing or drinking water"
      ],
      "other": [
        "PET",
        "PPT"
      ],
      "question": "Is it collapsible?",
      "selected": 5,
      "type": "multiple_choice"
    },
    {
      "assumed": false,
      "id": "e62d8e5e-9be1-463f-a0e1-b556d9c8d130",
      "options": [
        "For decorative purposes",
        "For storing or drinking water"
      ],
      "other": [
        "PET",
        "PPT"
      ],
      "question": "Is it collapsible?",
      "selected": 3,
      "type": "multiple_choice"
    },
    {
      "assumed": false,
      "id": "40d4f75d-f0f3-4d5e-aef3-46372d57ae94",
      "options": [
        "For decorative purposes",
        "For storing or drinking water"
      ],
      "other": [
        "PET",
        "PPT"
      ],
      "question": "What is the primary material?",
      "selected": 4,
      "type": "multiple_choice"
    }
  ],
  "session": {
    "historyDesc": [
      {
        "assumed": false,
        "id": "81d60381-3a92-444e-a498-4f8de86a579e",
        "selected": 4
      },
      {
        "assumed": false,
        "id": "ca9c6b9a-e542-4665-ae52-7726ebe12e86",
        "selected": 3
      },
      {
        "assumed": false,
        "id": "779e75eb-22c0-49cd-a3c2-5ffcc9a63321",
        "selected": 5
      },
      {
        "assumed": false,
        "id": "2057c406-cee8-4c3f-a3ed-68646bef7738",
        "selected": 0
      }
    ],
    "id": "20e0a4a8-b829-4326-bde1-0663d9fd4da0"
  },
  "suggestedHts": "70133710"
}

{
  "response": {
    "errors": [
      {
        "code": "4000",
        "message": "Invalid input provided"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "UJ0001",
        "message": "Invalid token or token is not present"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "4015",
        "message": "Unsupported Media Type"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "4022",
        "message": "Unprocessable Entity"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "5000",
        "message": "Internal Server Error"
      }
    ]
  }
}

POST

/interactive/{sessionId}

This endpoint facilitates the ongoing interactive process for refining a product description and determining its corresponding Harmonized Tariff Schedule (HTS) code. After initiating a session with the initial product description using the /interactive endpoint, users can continue their interacti

Header Name	Example
`transId`*	`"l"`
`transactionSrc`*	`"commodo aute anim"`

Request Payload

{
  "questions": [
    {
      "id": "4c6569d4-ff5f-44ec-ac9b-cc9047b604c3",
      "selected": 2
    },
    {
      "id": "8ff3680d-8d87-4450-b27c-458dbadfbad1",
      "selected": 1
    },
    {
      "id": "915a7e44-cf50-43eb-8f9c-d8928331319c",
      "selected": 2
    },
    {
      "id": "76188ed7-f583-4227-8377-3734d5036972",
      "selected": 4
    },
    {
      "id": "6174b599-475b-418d-8f08-663bcb056c1e",
      "selected": 2
    }
  ]
}

Response Payload

{
  "actualHts": "701337",
  "confidence": 0.68,
  "newProductDescription": "High-performance sports hydration bottle",
  "noMoreQuestions": false,
  "questions": [
    {
      "assumed": false,
      "id": "1277dc57-d7cd-496b-806c-772e1b9dc6d4",
      "options": [
        "For decorative purposes",
        "For storing or drinking water"
      ],
      "other": [
        "PET",
        "PPT"
      ],
      "question": "Is this item for food contact?",
      "selected": 2,
      "type": "multiple_choice"
    },
    {
      "assumed": false,
      "id": "8c14dfba-58a4-45c7-9472-59a92adda21c",
      "options": [
        "For decorative purposes",
        "For storing or drinking water"
      ],
      "other": [
        "PET",
        "PPT"
      ],
      "question": "Is it collapsible?",
      "selected": 5,
      "type": "multiple_choice"
    }
  ],
  "session": {
    "historyDesc": [
      {
        "assumed": false,
        "id": "874dea04-ff6e-475c-8478-088816571041",
        "selected": 4
      },
      {
        "assumed": true,
        "id": "649b14c0-e034-48b4-8d48-c2743db4531b",
        "selected": 2
      },
      {
        "assumed": false,
        "id": "54d0e0bc-490d-41b7-9c5a-7d405df8cdbd",
        "selected": 2
      },
      {
        "assumed": false,
        "id": "7d4a6a19-3f80-48c5-9211-0c1651038568",
        "selected": 5
      },
      {
        "assumed": false,
        "id": "1ea1b07f-bb2a-411e-96ad-4b97dad70856",
        "selected": 0
      }
    ],
    "id": "17d5c060-2440-489b-9de8-e837828a20f3"
  },
  "suggestedHts": "70133710"
}

{
  "response": {
    "errors": [
      {
        "code": "4000",
        "message": "Invalid input provided"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "UJ0001",
        "message": "Invalid token or token is not present"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "4015",
        "message": "Unsupported Media Type"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "4022",
        "message": "Unprocessable Entity"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "5000",
        "message": "Internal Server Error"
      }
    ]
  }
}

POST

/interactive/feedback/{sessionId}

Allows the user to provide feedback on a specific question of the overall session.

Request Payload

{
  "feedback": "The question was unclear",
  "id": "d14e9c12-7d86-401a-88f4-d50519fcef46",
  "sentiment": true
}

Response Payload

Missing schema or example in the OpenAPI spec.
Update the definition and recreate the mock server.

{
  "response": {
    "errors": [
      {
        "code": "4000",
        "message": "Invalid input provided"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "UJ0001",
        "message": "Invalid token or token is not present"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "4015",
        "message": "Unsupported Media Type"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "4022",
        "message": "Unprocessable Entity"
      }
    ]
  }
}

{
  "response": {
    "errors": [
      {
        "code": "5000",
        "message": "Internal Server Error"
      }
    ]
  }
}

Service Homepage: github.com/UPS-API/api-documentation/blob/main/InteractiveDescriptionGuidance.yaml

upslogisticsshippingcustomshtscompliance