How validation works
When using the Global Checkout API to calculate duties and taxes, a quoteId is returned. This ID must be passed into the UPS Ship API request using the QuoteID field.
During label creation, UPS validates the products provided in the InternationalForms inputs against the items supplied in the original Global Checkout API call. Some fields will be validated for exact matches, others will be automatically overwritten with quote values, and some will be ignored.
If validation succeeds, the landed cost guarantee applies. If certain fields have significant mismatches, the guarantee will be invalidated for that shipment, though the label request will still succeed.
Exact match requirements
The following fields must match between the original checkout request and the ship request. Mismatches in these fields will void the landed cost guarantee:
| UPS® Global Checkout field | Ship API field | Description |
|---|---|---|
quoteId | QuoteID | Ship API quote ID must match the landed cost ID associated with the order. |
quantity | Number | Quantity of each product in the cart |
amount | Value | Declared customs value per item |
countryOfOrigin | OriginCountryCode | Country where the product is manufactured (2-digit ISO code) |
currencyCode | CurrencyCode | The currency in which the item values are being passed |
productId or sku | PartNumber | All commodity identifiers must match between quote and shipment |
countryCode | CountryCode | Country code must match between quote and shipment. |
administrativeAreaCode | StateProvinceCode | If shipping to a country with administrative areas (e.g., Canada, Brazil), a state or province code is required. |
Field locations in Ship API JSON
The table below shows the exact JSON path for each required field in the UPS Ship API request:
| Required Field | Location in Shipment JSON |
|---|---|
QuoteID | Shipment>QuoteID |
Number | Shipment>ShipmentServiceOptions>InternationalForms>Product>Unit>Number |
Value | Shipment>ShipmentServiceOptions>InternationalForms>Product>Unit>Value |
OriginCountryCode | Shipment>ShipmentServiceOptions>InternationalForms>Product>OriginCountryCode |
CurrencyCode | Shipment>ShipmentServiceOptions>InternationalForms>CurrencyCode |
PartNumber | Shipment>ShipmentServiceOptions>InternationalForms>Product |
CountryCode | Shipment>ShipTo>Address>CountryCode |
StateProvinceCode | Shipment>ShipTo>Address>StateProvinceCode |
Additional validations:
- New products cannot be added at time of shipment that weren't in the original quote
- Product quantities cannot be increased beyond what was quoted
If a mismatch is detected during validation:
- The shipment will still proceed, but the guarantee is removed
- Duties and taxes will be invoiced directly to the shipper's UPS account
- No UPS-driven billing occurs for the duties and taxes
Overwritten fields
If the fields below are present in the Ship API request, they will be overwritten with the values associated with the quoteId. These fields are controlled by the original quote:
| UPS Global Checkout field | Ship API field | Description |
|---|---|---|
hsCode | CommodityCode | Harmonized system (HS) classification code |
description | Description | General description of the item |
amountSubtotals.shipping | FreightCharges > MonetaryValue | Freight charge amount, overwritten with the value from the order's amount subtotals |
currencyCode | CurrencyCode | Currency code overwritten with the item or order currency from the original quote |
| n/a | VendorCollectIDTypeCode | Updated to UPS' Tax ID for certain destinations (2-digit ISO codes) |
| n/a | VendorCollectIDNumber | Updated to UPS' Tax ID for certain destinations (2-digit ISO codes) |
Any additional cart data not used in the validation or overwrite processes will be ignored by the backend.
Validation outcomes
If validation succeeds
When the InternationalForms data matches what was originally quoted:
- The landed cost guarantee will apply
- UPS will bill only the quoted amount in duties, taxes, and fees along with your transportation invoice
- The label will display "P/P TPR" in the Billing Terms section
- Fields listed in the "Fields that will be overwritten" section may change
If validation fails
If the InternationalForms data does not match what was originally quoted:
- Label request will succeed, but billing terms will not show "P/P TPR"
- The landed cost guarantee will not apply
- Duties and taxes will be invoiced to the shipper, regardless of the incoterms in the label request
- The returned duty and tax values may be considered informational only
- Values in the
InternationalFormswill not be overwritten
Note: If validation fails for any reason, the API response will include an alert message stating "Global Checkout guarantee not applied". In this case, the order will not be guaranteed.
Best practices
To ensure successful validation and maintain landed cost guarantees:
- Always pass a valid quote ID when creating a UPS label
- Implement measures to ensure the same cart values are provided during both checkout and label creation
- If order changes commonly occur between quote and shipment, implement a re-quoting mechanism in your Order Management System at any point where orders may be edited
- Keep consistent product quantities between the quote and shipment request
- Ensure address data remains unchanged between quote and shipment
- Review validation failures regularly to identify patterns and implement corrections
Consistent mismatches may lead to customer complaints, customs clearance delays, or underpaid duty and tax liabilities.
Shipment validation
Understand how UPS validates shipments to maintain landed cost guarantees.
When you create a shipment using a UPS® Global Checkout quote, UPS validates that the information provided at time of shipment matches what was used to generate the original checkout quote. This validation ensures that the guaranteed landed cost remains accurate for the respective shipment.
Looking for code examples? See the Ship API integration guide for complete request/response examples showing how to pass the Quote ID.