HomeUPS® Global Checkout Label setup Ship API

UPS Ship API integration

Pass your Quote ID to the UPS Ship API to maintain guaranteed landed costs.

When creating shipping labels through the UPS Ship API, you must include the Quote ID from your UPS Global Checkout landed cost calculation. This ensures the guaranteed pricing remains valid and duties/taxes are properly billed.

Prerequisites

Before integrating with the UPS Ship API:

Calculate a landed cost using the UPS Global Checkout API to obtain a Quote ID
Store the Quote ID - The id returned from landedCostCalculateWorkflow (e.g., lc-967c420f1d104a48b980e42d92e8f21b)
Have UPS Ship API access - Contact UPS for API credentials if needed

Pass the Quote ID

The Quote ID must be included in the Shipment object of your UPS Ship API request using the QuoteID field:

Shipment > QuoteID

When UPS processes the shipment, it validates the Quote ID and checks that the shipment details match the original landed cost calculation.

Example request

The following example shows a complete UPS Ship API request with the Quote ID included. Key fields for validation are highlighted in the comments.

UPS SHIP API REQUEST

{
  "ShipmentRequest": {
    "Request": {
      "SubVersion": "2403",
      "RequestOption": "nonvalidate",
      "TransactionReference": {
        "CustomerContext": "Global Checkout Order"
      }
    },
    "Shipment": {
      "QuoteID": "lc-967c420f1d104a48b980e42d92e8f21b",
      "Description": "Mcquade slim fit jeans",
      "Shipper": {
        "Name": "Fashion Retailer Inc",
        "AttentionName": "Shipping Department",
        "Phone": {
          "Number": "8015551234"
        },
        "ShipperNumber": "YOUR_SHIPPER_NUMBER",
        "Address": {
          "AddressLine": ["123 Commerce Drive"],
          "City": "St George",
          "StateProvinceCode": "UT",
          "PostalCode": "84790",
          "CountryCode": "US"
        }
      },
      "ShipTo": {
        "Name": "John Smith",
        "AttentionName": "John Smith",
        "Phone": {
          "Number": "4165551234"
        },
        "Address": {
          "AddressLine": ["456 Queen Street West"],
          "City": "Toronto",
          "StateProvinceCode": "ON",
          "PostalCode": "K1L 6B6",
          "CountryCode": "CA",
          "ResidentialAddressIndicator": {}
        }
      },
      "ShipFrom": {
        "Name": "Fashion Retailer Inc",
        "AttentionName": "Warehouse",
        "Phone": {
          "Number": "8015551234"
        },
        "Address": {
          "AddressLine": ["123 Commerce Drive"],
          "City": "St George",
          "StateProvinceCode": "UT",
          "PostalCode": "84790",
          "CountryCode": "US"
        }
      },
      "PaymentInformation": {
        "ShipmentCharge": [
          {
            "Type": "01",
            "BillShipper": {
              "AccountNumber": "YOUR_SHIPPER_NUMBER"
            }
          }
        ]
      },
      "Service": {
        "Code": "11",
        "Description": "UPS Standard"
      },
      "ShipmentServiceOptions": {
        "InternationalForms": {
          "FormType": ["01"],
          "Contacts": {
            "SoldTo": {
              "Name": "John Smith",
              "AttentionName": "John Smith",
              "Phone": {
                "Number": "4165551234"
              },
              "Address": {
                "AddressLine": ["456 Queen Street West"],
                "City": "Toronto",
                "StateProvinceCode": "ON",
                "PostalCode": "K1L 6B6",
                "CountryCode": "CA"
              }
            }
          },
          "CurrencyCode": "USD",
          "InvoiceDate": "20250204",
          "ReasonForExport": "SALE",
          "TermsOfShipment": "DDP",
          "Product": [
            {
              "Description": "Mcquade slim fit jeans",
              "Unit": {
                "Number": "1",
                "UnitOfMeasurement": {
                  "Code": "EA",
                  "Description": "Each"
                },
                "Value": "60.50"
              },
              "ProductWeight": {
                "UnitOfMeasurement": {
                  "Code": "LBS",
                  "Description": "Pounds"
                },
                "Weight": "2.0"
              },
              "PartNumber": "34341",
              "OriginCountryCode": "CN",
              "NumberOfPackagesPerCommodity": "1"
            }
          ]
        }
      },
      "Package": [
        {
          "Packaging": {
            "Code": "02",
            "Description": "Customer Supplied Package"
          },
          "Dimensions": {
            "UnitOfMeasurement": {
              "Code": "IN",
              "Description": "Inches"
            },
            "Length": "12",
            "Width": "10",
            "Height": "4"
          },
          "PackageWeight": {
            "UnitOfMeasurement": {
              "Code": "LBS",
              "Description": "Pounds"
            },
            "Weight": "2.0"
          }
        }
      ]
    },
    "LabelSpecification": {
      "LabelImageFormat": {
        "Code": "ZPL"
      },
      "LabelStockSize": {
        "Height": "6",
        "Width": "4"
      }
    }
  }
}

Field mapping reference

The following fields in the UPS Ship API request must match the values from your original UPS Global Checkout landed cost calculation:

Global Checkout field	Ship API field	Ship API location
`landedCostCalculateWorkflow.id`	`QuoteID`	`Shipment>QuoteID`
`itemCreateWorkflow.quantity`	`Number`	`Shipment>ShipmentServiceOptions>InternationalForms>Product>Unit>Number`
`itemCreateWorkflow.amount`	`Value`	`Shipment>ShipmentServiceOptions>InternationalForms>Product>Unit>Value`
`itemCreateWorkflow.countryOfOrigin`	`OriginCountryCode`	`Shipment>ShipmentServiceOptions>InternationalForms>Product>OriginCountryCode`
`itemCreateWorkflow.currencyCode`	`CurrencyCode`	`Shipment>ShipmentServiceOptions>InternationalForms>CurrencyCode`
`itemCreateWorkflow.productId` or `sku`	`PartNumber`	`Shipment>ShipmentServiceOptions>InternationalForms>Product>PartNumber`
`partyCreateWorkflow.location.countryCode` (DESTINATION)	`CountryCode`	`Shipment>ShipTo>Address>CountryCode`
`partyCreateWorkflow.location.administrativeAreaCode` (DESTINATION)	`StateProvinceCode`	`Shipment>ShipTo>Address>StateProvinceCode`

Validation behavior

Successful validation

When the Ship API request matches your Global Checkout quote:

The landed cost guarantee applies
Label displays "P/P TPR" in the billing terms
UPS bills only the quoted duties, taxes, and fees
Customer's prepaid duties/taxes are applied

Failed validation

If there's a mismatch between the quote and shipment:

Label creation still succeeds
The guarantee is removed
Billing terms will not show "P/P TPR"
Duties and taxes are invoiced to your UPS account
API response includes alert: "Global Checkout guarantee not applied"

Common validation issues

Issue	Cause	Solution
Missing Quote ID	`QuoteID` field not included	Add the Quote ID from your landed cost calculation
Quantity mismatch	`Number` exceeds quoted quantity	Ship same or fewer items than quoted
Product not found	`PartNumber` doesn't match `productId` or `sku`	Ensure part numbers match exactly
Country mismatch	`CountryCode` differs from quote	Ship to the same destination country
New products added	Products in shipment weren't in quote	Only ship items included in the original quote

Best practices

Store the Quote ID immediately after calculating landed cost - you'll need it when creating the label
Don't modify orders between checkout and shipment - changes invalidate the quote
Use consistent identifiers - ensure productId or sku values are identical in both API calls
Verify "P/P TPR" appears on printed labels to confirm the guarantee is active
Monitor API alerts - check responses for "Global Checkout guarantee not applied" warnings
Re-quote if needed - if order changes are required, calculate a new landed cost before shipping

Need help?

For Ship API integration support, contact globalcheckoutsupport@ups.com with:

Your UPS shipper number
Sample API requests and responses
Quote IDs and tracking numbers for problem shipments