Agent-Skills.md

Agent Skills: UPS Shipping APIs

UPS Shipping

UncategorizedID: nevaberry/nevaberry-plugins/ups-shipping-knowledge-patch

Repository

nevaberry/nevaberry-plugins
NevaberryLicense: MIT
23

Install this agent skill to your local

pnpm dlx add-skill https://github.com/Nevaberry/nevaberry-plugins/tree/HEAD/plugins/knowledge-patch/patches-codex/ups-shipping-knowledge-patch

Skill Files

Browse the full folder contents for ups-shipping-knowledge-patch.

Download Skill

Loading file tree…

plugins/knowledge-patch/patches-codex/ups-shipping-knowledge-patch/SKILL.md

Skill Metadata

Name
ups-shipping-knowledge-patch
Description
UPS Shipping

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

| Reference | Topics | | --- | --- | | Migrations and platform | Track Alert v2, schema migrations, array consistency, certificates, OAuth, portal security, webhooks, and the UPS MCP server | | Shipping, rating, and tracking | Error codes, surcharges, Time in Transit, Roadie, Delivery Intercept, and shipment linkage | | Pickup, freight, and supply chain | Smart Pickup, Lab Logistics, SCS ingestion, Forwarding, and TradeDirect | | International compliance and assurance | Delivery tokens, customs, Windsor Lane, tax IDs, Global Checkout, Export Assure, and address confidence |

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:

| Version | APIs | | --- | --- | | v2403 | Shipping, Rating, Pickup, Dangerous Goods Chemical Reference Data | | v2 | Dangerous Goods Acceptance Audit Pre-check, Pre Notification, Paperless Documents, Locator, Quantum View, Ship Void, Address Validation, Landed Cost |

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:

| Surface | Codes and changes | | --- | --- | | Shipping / Label Recovery | 9801061, 9801062, 9801064, 9801065, 9801067 | | Shipping | 120466; description changed for 120200 | | Dangerous Goods | 9190048 | | Pre Notification | 9290059 |

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

| Need | Surface | | --- | --- | | Require a PIN before package release without exposing it directly | Protected Delivery Token | | Obtain current UPS-shipment compliance requirements before submission | Customs Detail | | Get guaranteed international duty-and-tax quotes at checkout | Global Checkout GraphQL API | | Guide goods descriptions and check destination-specific commodity compliance | Export Assure | | Get a pre-label address-confidence score based on delivery data | DeliveryDefense Address Confidence |

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

| Need | API | | --- | --- | | Create and manage air, ocean, or ground freight-forwarding shipments | Forwarding API | | Synchronize WMS orders and updates for order and inventory visibility | SCS Inventory | | Ingest operational events in near real time | SCS Logistics | | Send TMS shipments and updates to the UPS Supply Chain Symphony datastore | SCS Transportation | | Ship directly from manufacturers to international end consumers | TradeDirect |

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