Ups Shipping Knowledge Patch

UPS Shipping APIs

Use this skill for current UPS API integration work involving shipping, rating, tracking, pickup, OAuth, webhooks, international compliance, freight, or supply-chain services.

Reference index

Breaking changes and migration priorities

Track Alert v2

Version 2 of Track Alert and Track Alert with Photo removes the destination object. Clients migrating to v2 must not require or deserialize that object.

Both premium APIs are available globally. Their events include gmtOffset in (-/+)HH.MM form to explain local-time conversion.

Removed and relaxed schema fields

Do not expect these fields on LabelDelivery_EMail:

• UndeliverableEMailAddress
• FromEMailAddress
• FromName
• Memo
• Subject
• SubjectCode

Master_SoldTo.AttentionName is no longer required.

Pickup creation adds Notification and PickupCreationRequest_Notification, and makes StateProvince optional.

Open Account adds:

• RateTypeCode
• RateConstructCode

Track by Reference Number adds:

• destCountry
• destZip
• shipperNum

Consistent array response paths

Use API versions that consistently return fields documented as arrays:

Older paths retain inconsistent scalar-or-array behavior for compatibility.

Locally maintained certificate stores

Clients connecting to onlinetools.ups.com with a locally maintained certificate trust store must follow the DigiCert migration guidance and update that store.

Browser clients and systems that automatically trust public certificate authorities need no action.

Request requirements that can block or warn

• Mexico shipment requests require tax-ID information, matching the existing requirement for Indonesia and Vietnam.
• Roadie rating requests require AddressLine.
• Windsor Lane shipments require a commercial invoice or the API returns a warning.

OAuth and developer platform quick reference

Callback registration

Authorization-code callbacks may use localhost. A localhost callback must use http:// and include a port.

Supplied state and scope query parameters are returned to the client.

Enter multiple callback URLs as a comma-separated list with no spaces:

http://localhost:3000/callback,https://shop.example.com/ups/callback

Steppingstone migrations

Use OAuth Steppingstone mode when a migration cannot yet replace SOAP/XML payloads with REST payloads. It accepts the existing SOAP/XML format while moving authentication to OAuth 2.0.

Portal and credential controls

• Accessing API credentials or an application in the Developer Portal prompts users to reauthenticate with MFA.
• Commerce Guard and Global Checkout can be requested through the application add/edit flow.
• Manage Webhook Credentials configures and maintains webhook credentials centrally instead of separately at each integration point.
• UPS provides an MCP server with Track and Address Validation tools for agent integrations.

Shipping, rating, and tracking quick reference

Expanded known error codes

Error handlers must accept the following as known UPS codes:

Fees and transit indicators

• Shipping and Rating recognize surcharge code 573 for the International Process Fee.
• Rating can return warning 112259 when the fee is added to a shipment.
• Time in Transit requests accept premierIndicator to mark a shipment that contains a Premier package.

Roadie and RoadieXD

Rating versions 2409 or newer return Zone for Roadie. Shipping and Rating also add RoadieXD service types, subtypes, accessorials, and surcharge codes.

Delivery Intercept

Delivery Intercept supports automated intercept requests. Call its eligibility endpoint to determine which intercept type is valid before submitting a request. Add the API through the standard application add/edit flow.

Master and child shipment linkage

• Create World Ease master and child shipments with the Shipping API, including World Ease packages originating in Canada.
• Relate consolidated Worldwide Economy packages to their master carton with MasterCartonID for cross-level tracking.

International and delivery quick reference

Windsor Lane

Shipping supports:

• Northern Ireland-to/from-GB routes where the GB postcode begins BT.
• Northern Ireland-to/from-EU routes.

The update adds ConsgineeTypevalue and ShipmentRiskEnteringEU.

Choose the compliance or assurance surface

Global Checkout country, province, and measurement-unit codes are defined in a dedicated appendix.

Pickup, freight, and supply-chain quick reference

Smart Pickup choices

• Smart Pickup API triggers Smart Pickups independently of a merchant's platform integration.
• Smart Pickup Widget owns authentication, scheduling logic, and UPS API communication.
• Pickup Notification Preferences API manages notification settings at the account level.
• UPS Lab Logistics Pickup Points lets clinics and laboratories schedule daily or date-specific Smart Pickups through a centralized API.

Freight and ingestion choices

Forwarding shipments can be billed to a shipper, receiver, or third-party account. The Shipping API can create TradeDirect shipments.