UPS Customs Detail API Virtual Sandbox
Manage compliance requirements and validate shipment data fields for international UPS shipping.
The UPS Customs Detail API provides up-to-date compliance requirements for data fields required for international shipments. It allows developers to validate field values and manage collection settings, ensuring that shipment data meets evolving country-specific regulations without requiring frequent code changes.
Use this hosted sandbox to simulate UPS Customs Detail API 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 customs field requirements, test data submission payloads, verify compliance field mapping for specific destination countries, and handle error responses for invalid shipment data before integrating with UPS production systems.
Customs Detail(2 operations)
POST
| Header Name | Example |
|---|---|
transId* | "irure aute" |
transactionSrc* | "dolore reprehenderit est" |
Content-Type* | "irure" |
registrationId | "3DA124234342" |
{
"actionType": "save",
"shipperNumber": "1443YY",
"trackingNumber": "1Z1443YY0161231327",
"invoiceFormGroupId": "1F1443YY0161231327",
"shipmentType": "Gift",
"shipmentWeight": 32456,
"shipmentWeightUnit": "KGS",
"shipmentValue": 10000,
"shipmentValueCurrency": "USD",
"userRoles": [
"Importer",
"Exporter"
],
"commerceModel": "B2B",
"shipmentMetaData": [
{
"groupKey": "DE-EXP-MRN",
"fields": [
{
"fieldKey": "DEEORI",
"fieldValue": "MN123456789"
}
]
},
{
"groupKey": "IN-EXP-CSB",
"fields": [
{
"fieldKey": "CSBType",
"fieldValue": "3"
},
{
"fieldKey": "IECCode",
"fieldValue": "1234567890"
}
]
}
],
"products": [
{
"productId": "PART-001",
"productDescription": "Medical device",
"lineNumber": 1,
"commodityCode": "3821000010",
"productMetaData": [
{
"groupKey": "US-IMP-FDA",
"fields": [
{
"fieldKey": "MnuNa",
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"fieldValue": "UPS Labs"
},
{
"fieldKey": "MnuAdLn1Te",
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"fieldValue": "55 Glenlake Pkwy NE"
},
{
"fieldKey": "MnuAdLn2Te",
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"fieldValue": "Suite 400"
},
{
"fieldKey": "MnuAdLn3Te",
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"fieldValue": "Building C"
},
{
"fieldKey": "MnuCtyNa",
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"fieldValue": "Atlanta"
},
{
"fieldKey": "MnuStPrvCd",
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"fieldValue": "GA"
},
{
"fieldKey": "MnuCtyCd",
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"fieldValue": "US"
},
{
"fieldKey": "MnuPslCd",
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"fieldValue": "30301"
}
]
}
]
},
{
"productId": "PART-002",
"productDescription": "Sample pharma goods",
"commodityCode": "300490",
"productMetaData": [
{
"groupKey": "US-IMP-232",
"fields": [
{
"fieldKey": "NddUseAutIr",
"regulationSections": [
{
"sectionKey": "Alum"
}
],
"fieldValue": "Yes"
},
{
"fieldKey": "AlumCnxPr",
"regulationSections": [
{
"sectionKey": "Alum"
}
],
"fieldValue": "Test"
},
{
"fieldKey": "AlumPrc1CnyCd",
"regulationSections": [
{
"sectionKey": "Alum"
}
],
"fieldValue": "Testing"
},
{
"fieldKey": "Prc2CnyCd",
"regulationSections": [
{
"sectionKey": "Alum"
}
],
"fieldValue": "Go"
}
]
}
]
}
]
}Missing schema or example in the OpenAPI spec.
Update the definition and recreate the mock server.{
"response": {
"errors": [
{
"code": "105.000",
"message": "Malformed JSON request"
},
{
"code": "105.004",
"message": "Field value is required",
"description": "VALUE_REQUIRED",
"field": "shipperNumber",
"value": null
}
]
}
}{
"response": {
"errors": [
{
"code": "105.401",
"message": "Invalid token or token is not present",
"description": null,
"field": null,
"value": null
}
]
}
}{
"response": {
"errors": [
{
"code": "105.001",
"description": "INVALID_FIELD_VALUE",
"field": "importCountryCode",
"message": "Supplied value was not in the correct range of valid values.",
"value": "USA"
}
]
}
}{
"response": {
"errors": [
{
"code": "105.500",
"message": "Internal Server Error",
"description": "INTERNAL_ERROR",
"field": null,
"value": null
}
]
}
}GET
| Query Parameter Name | Example |
|---|---|
import_country_code | US |
export_country_code | IT |
locale | en-US |
commodity_codes | 2926400000,3003395000 |
shipment_type | Gift |
shipment_weight | 32456 |
shipment_weight_unit | KGS |
shipment_value | 10000 |
shipment_value_currency | USD |
user_roles | ["Importer","Exporter"] |
commerce_model | B2B |
| Header Name | Example |
|---|---|
transId* | "ex pariatur" |
transactionSrc* | "quis dolore minim aliqua" |
Content-Type* | "irure ut cillum eu" |
{
"commodityCodes": [
{
"commodityCode": "2926400000",
"regulations": [
{
"regulation": "FDA",
"regulationSections": [
{
"sectionKey": "Bio"
}
]
}
]
},
{
"commodityCode": "3003395000",
"regulations": [
{
"regulation": "FDA",
"regulationSections": [
{
"sectionKey": "Bio"
}
]
}
]
},
{
"commodityCode": "All",
"regulations": [
{
"regulation": "FDA",
"regulationSections": [
{
"sectionKey": "Foo"
}
]
}
]
}
],
"fieldGroups": [
{
"countryCode": "US",
"countryName": "UNITED STATES OF AMERICA",
"shipmentType": "Import",
"groupKey": "US-IMP-FDA",
"details": "This is for US import FDA fields",
"regulation": "FDA",
"regulationSections": [
{
"sectionKey": "Cos",
"sectionName": "Cosmetics"
},
{
"sectionKey": "Bio",
"sectionName": "Biologics"
},
{
"sectionKey": "Dev",
"sectionName": "Device"
},
{
"sectionKey": "Foo",
"sectionName": "Food"
}
],
"validationRules": [
{
"rule": "SteelContentPercentage + AluminumContentPercentage + CopperContentPercentage <= 100"
},
{
"errorMessage": "Steel, aluminum, and copper percentages cannot total more than 100."
}
],
"fields": [
{
"sectionKey": "MnuNa",
"label": "Manufacturer Name",
"order": "1",
"tooltip": "Type of shipping bill to be processed for the shipment",
"isRequired": "C",
"requirementConditions": [
{
"fieldKey": "MnuPslCd",
"operator": "!=",
"value": ""
}
],
"displayConditions": [
{
"ruleType": "request",
"fieldKey": "shipmentWeight",
"operator": ">",
"value": "5000",
"unit": "KGS"
},
{
"ruleType": "fieldInput",
"fieldKey": "SteelContentPercentage",
"operator": ">",
"value": "0",
"unit": null
}
],
"fieldType": "textbox",
"allowedValueCount": 1,
"validation": {
"minLength": null,
"maxLength": null,
"errorMessage": "Enter a valid value",
"dataType": "Text",
"regexPattern": null,
"listValues": []
},
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"keyAlias": "ManufacturerName",
"level": "Product",
"includeOnInvoice": false
},
{
"sectionKey": "MnuPslCd",
"label": "Manufacturer Postal Code",
"order": "8",
"tooltip": "The postal code address of the manufacturer for the product",
"isRequired": "Y",
"requirementConditions": null,
"displayConditions": null,
"fieldType": "textbox",
"allowedValueCount": 1,
"validation": {
"minLength": null,
"maxLength": null,
"errorMessage": "Enter a valid value",
"dataType": "Text",
"regexPattern": null,
"listValues": []
},
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"keyAlias": "ManufacturerPostalCode",
"level": "Product"
},
{
"sectionKey": "MnuAdLn1Te",
"label": "Manufacturer Address Line 1",
"order": "1",
"tooltip": "Line 1 of the address of the manufacturer for the product",
"isRequired": "N",
"requirementConditions": null,
"displayConditions": null,
"fieldType": "textbox",
"allowedValueCount": 1,
"validation": {
"minLength": null,
"maxLength": null,
"errorMessage": "Enter a valid value",
"dataType": "Text",
"regexPattern": null,
"listValues": []
},
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"keyAlias": "ManufacturerAddressLine1",
"level": "Product"
},
{
"sectionKey": "MnuAdLn2Te",
"label": "Manufacturer Address Line 2",
"order": "1",
"tooltip": "Line 2 of the address of the manufacturer for the product",
"isRequired": "N",
"requirementConditions": null,
"displayConditions": null,
"fieldType": "textbox",
"allowedValueCount": 1,
"validation": {
"minLength": null,
"maxLength": null,
"errorMessage": "Enter a valid value",
"dataType": "Text",
"regexPattern": null,
"listValues": []
},
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"keyAlias": "ManufacturerAddressLine2",
"level": "Product"
},
{
"sectionKey": "MnuAdLn3Te",
"label": "Manufacturer Address Line 3",
"order": "1",
"tooltip": "Line 3 of the address of the manufacturer for the product",
"isRequired": "N",
"requirementConditions": null,
"displayConditions": null,
"fieldType": "textbox",
"allowedValueCount": 1,
"validation": {
"minLength": null,
"maxLength": null,
"errorMessage": "Enter a valid value",
"dataType": "Text",
"regexPattern": null,
"listValues": []
},
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"keyAlias": "ManufacturerAddressLine3",
"level": "Product"
},
{
"sectionKey": "MnuCtyNa",
"label": "Manufacturer City Name",
"order": "1",
"tooltip": "Line 3 of the address of the manufacturer for the product",
"isRequired": "N",
"requirementConditions": null,
"displayConditions": null,
"fieldType": "textbox",
"allowedValueCount": 1,
"validation": {
"minLength": null,
"maxLength": null,
"errorMessage": "Enter a valid value",
"dataType": "Text",
"regexPattern": null,
"listValues": []
},
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"keyAlias": "ManufacturerAddressLine3",
"level": "Product"
},
{
"sectionKey": "MnuStPrvCd",
"label": "Manufacturer State/Province Code",
"order": "1",
"tooltip": "The state/province for the address of the manufacturer for the product",
"isRequired": "N",
"requirementConditions": null,
"displayConditions": null,
"fieldType": "textbox",
"allowedValueCount": 1,
"validation": {
"minLength": null,
"maxLength": null,
"errorMessage": "Enter a valid value",
"dataType": "Text",
"regexPattern": null,
"listValues": []
},
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"keyAlias": "ManufacturerStateProvinceCode",
"level": "Product"
},
{
"sectionKey": "MnuCtyCd",
"label": "Manufacturer Country Code",
"order": "1",
"tooltip": "The country code for the address of the manufacturer for the product",
"isRequired": "N",
"requirementConditions": null,
"displayConditions": null,
"fieldType": "textbox",
"allowedValueCount": 1,
"validation": {
"minLength": null,
"maxLength": null,
"errorMessage": "Enter a valid value",
"dataType": "Text",
"regexPattern": null,
"listValues": []
},
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"keyAlias": "ManufacturerCountryCode",
"level": "Product"
},
{
"sectionKey": "MnuPslCd",
"label": "Manufacturer Postal Code",
"order": "1",
"tooltip": "The postal code address of the manufacturer for the product",
"isRequired": "Y",
"requirementConditions": null,
"displayConditions": null,
"fieldType": "textbox",
"allowedValueCount": 1,
"validation": {
"minLength": null,
"maxLength": null,
"errorMessage": "Enter a valid value",
"dataType": "Text",
"regexPattern": null,
"listValues": []
},
"regulationSections": [
{
"sectionKey": "Cos"
},
{
"sectionKey": "Bio"
},
{
"sectionKey": "Dev"
},
{
"sectionKey": "Foo"
}
],
"keyAlias": "ManufacturerPostalCode",
"level": "Product"
}
]
}
]
}{
"response": {
"errors": [
{
"code": "105.401",
"message": "Invalid token or token is not present",
"description": null,
"field": null,
"value": null
}
]
}
}{
"response": {
"errors": [
{
"code": "105.001",
"description": "INVALID_FIELD_VALUE",
"field": "importCountryCode",
"message": "Supplied value was not in the correct range of valid values.",
"value": "USA"
}
]
}
}{
"response": {
"errors": [
{
"code": "105.500",
"message": "Internal Server Error",
"description": "INTERNAL_ERROR",
"field": null,
"value": null
}
]
}
}Service Homepage: github.com/UPS-API/api-documentation/blob/main/CustomsDetailV2.yaml
upslogisticscustomsshippingcompliance