UPS tracking

UPS supports both tracking known shipment numbers and discovering shipments through Quantum View Data. Both integrations use the customer's own UPS OAuth application credentials.

Setup

1. In UPS Developer Portal, give the customer's application access to Tracking and Quantum View. Ensure its UPS account is associated with the application.
2. In Scope, open Data → Transporters → UPS → Settings. Save the Client ID and Client Secret and add the customer's UPS account number. Credentials are encrypted in the existing retailer credential store.
3. For known tracking numbers supplied by a WMS, use the normal order/shipment tracking API. UPS is polled through the existing tracking scheduler when the organization has no enabled Quantum View subscription. A saved but disabled subscription does not suppress polling.
4. For automatic discovery, first create a Quantum View Data subscription with UPS. API permissions alone do not create this subscription. In Scope, select the customer number and leave the subscription name blank to retrieve all subscriptions accessible to the saved credentials. Optionally enter an exact subscription name to restrict retrieval. No inbound/outbound selection is required.
5. Choose the reference field used for order matching, and the timezone for timestamps without a UPS offset. Save the subscription; it starts disabled. A Skrym administrator can enable it once the UPS-side setup is complete.

Subscription mutation controls are restricted to Skrym administrators. Organization users can inspect their subscriptions and ingestion health. Use credentials whose accessible subscriptions belong to the intended organization. The selected customer number is used when initializing shipments; it is not a UPS-side filter on the returned subscriptions. An inbound UPS feed is not automatically classified as a customer return.

Choosing the event source

An enabled Quantum View subscription selects Quantum View for all UPS shipments in that organization, including shipments supplied by a WMS. The enabled feeds must cover the organization’s UPS accounts and required directions. These shipments are excluded when the scheduled polling job selects its next batch. Poll requests that were already queued still run, and the user-triggered PollShipments endpoint is an explicit override that also queues a poll.

Disabling the last enabled Quantum View subscription restores normal polling eligibility for existing and new shipments. Normal polling rules still apply, including shipment status, next-poll time and failed-poll limits. A temporarily failing but enabled subscription continues to select Quantum View; retrieval errors do not automatically enable shipment polling.

The transporter’s api-polling method remains the fallback capability. Subscription state determines whether the automatic scheduler queues shipment polling. Quantum View still has its separate 15-minute subscription retrieval job.

Order references and shipment identity

The default order reference is the first shipment-level UPS reference. Choose package-level references or filter by UPS reference position and/or code when your WMS stores its order identifier elsewhere. If no matching reference exists, the package tracking number is used. For a manifest grouping multiple packages, the first package supplies the package-level order reference.

Existing shipments are matched within the organization using tracking references on tracked_shipment and tracked_parcel before anything is created. Packages discovered through Quantum View or the Tracking API are saved as tracked parcels, so later scans can resolve them without a separate UPS alias table. Manifest packages can be grouped in one shipment. If earlier scans or WMS imports already created separate shipments, they are enriched without merging them or changing their order associations. Multiple shipments can belong to the same tracked order. When Quantum View creates a shipment for the first time, it queues one Tracking API poll to enrich the shipment with the available history and details. Matching an existing shipment does not queue this initial poll.

Later records enrich missing addresses, service information, parcels, and delivery estimates. Reference configuration changes apply to future discovery; they do not move existing shipments to another order.

Retrieval, retries, and health

Quantum View is polled every 15 minutes. The first import requests the available previous seven days; subsequent requests overlap the previous completed window by one hour. The request includes a date window and omits the name filter when it is blank. All returned subscription groups are processed, and their source names are retained on raw records. Continuation bookmarks retain the original request window. A database lease prevents concurrent retrieval for the same subscription.

Each extracted record is stored once in the shared raw_event table. Its ID and a snapshot of the subscription configuration are published to the ordered ups-quantum-record-1 Pub/Sub topic. Both retrieval requests and records use the UPS subscription ID as their ordering key, so records from one subscription are processed in publication order without serializing unrelated subscriptions. The retrieval cursor advances only after every record in the page has been published successfully. A partial publication or crash causes the page to be retrieved again; stable raw-record and event keys make duplicate deliveries safe. Full page payloads are not retained separately. Ordinary Tracking API responses also use raw_event.

Record processing runs independently of retrieval. Failed records return an error to Pub/Sub for up to five retries, with backoff between 30 seconds and 15 minutes. Records from other subscriptions can continue processing while later records for the failing subscription retain their order. Raw records remain available after retry exhaustion; operators must inspect failed deliveries and arrange replay with the original subscription snapshot. There is no database inbox or pending-record count.

Retrieve now schedules retrieval for an enabled subscription, including its normal one-hour overlap; it does not replay older failed Pub/Sub messages. Disable a subscription to stop new scheduled retrieval. Already published messages continue processing using their captured configuration. Configuration edits require the subscription to be disabled and its current paginated retrieval to have completed.

Scope shows the last completed retrieval window, last successfully processed record, and retrieval/publishing errors. Processing failures are reported by the Pub/Sub consumer and its trace. A retention-gap warning means polling fell behind UPS's seven-day retrieval window. Contact UPS for missing historical data; the integration does not silently claim it was imported.

Events and timestamps

Default mappings cover label creation, collection, transit, terminals, delivery attempts, delivery, pickup availability, exceptions, cancellation, and returns, with English and Swedish messages. UPS processing status 040/activity ZP and Quantum View Access Point delivery represent pickup availability, not delivery to the recipient. Notification failures are not pickup events.

Detailed Tracking codes use TRACK:<type>:<activity-code>:<processing-status>. Mapping lookup checks an organization override for the detailed code first, followed by the documented activity or TRACK:STATUS:<processing-status> mapping, then a broad UPS status type. Quantum View uses QV:<record-kind> and QV:Generic:<activity-type>; exceptions retain status and reason codes. Unknown events are retained and reported through the standard unknown-input flow. No free-text description matching is used to infer delivery.

Equivalent events use parcel identity, semantic event, timestamp, and locality to prevent duplicate tracking events across the two feeds. Both source payloads remain in raw_event. Uncertain matches, including conflicting localities or unrelated exceptions, are kept separate.

Explicit UPS GMT timestamps or offsets take precedence. Offset-free timestamps use the configured subscription timezone, initially Europe/Stockholm. Tracking API polling uses Europe/Stockholm for offset-free timestamps. Both UPS paths use the event mapping’s direction, defaulting unknown direction to outbound, like PostNord Pulse. Return-specific mappings remain inbound. Quantum View retains its timezone in each Pub/Sub message; no shipment context table is needed. Origin and destination information is saved when supplied by UPS. Manifest label events use the UPS file creation timestamp because the manifest does not supply a shipment event timestamp.

Environments and troubleshooting

Production uses https://onlinetools.ups.com; other environments default to UPS's customer integration environment at https://wwwcie.ups.com. Credentials and OAuth token caches are isolated by organization and environment. Sandbox data does not prove that production subscriptions or account permissions are configured.

For authentication failures, check the Client ID/Secret, application API permissions, and account linkage. For an empty feed, verify UPS-side configuration and the optional subscription-name filter, if supplied. For processing failures, inspect the subscription's traces and referenced raw records, fix configuration or mapping issues, and retry. Do not include credentials in screenshots, logs, or support messages.

API references: Tracking, Quantum View, and UPS Tracking API codes.