Ellipse Gradient for Header

UPS Integration Guide

Connect enterprise order, warehouse, and customer-service systems with UPS REST APIs, tracking notifications, shipping operations, and OAuth 2.0.

UPS integration options at a glance

UPS provides current REST APIs for shipping and label generation, tracking, rating, address validation, time-in-transit estimates, pickup operations, and related services. Applications generally authenticate with OAuth 2.0, while older implementations may use legacy access-key credentials. UPS also supports webhook-style tracking notifications for selected events and use cases, with scheduled Tracking API requests available where webhook coverage is incomplete. Labels and shipping documents can be returned through applicable APIs. Martini can consume these APIs, receive supported notifications, secure credentials in environment-specific secrets, transform UPS JSON and document payloads, and orchestrate retries, reconciliation, and downstream updates.

Integration pointSupported by UPS?Common use casesHow Martini supports it
REST APIsYesUPS REST APIs support shipping and label generation, tracking, rating, address validation, time-in-transit, pickup, location, service lookup, and selected paperless-document operations.Martini can consume the UPS REST APIs from workflows, map JSON requests and responses, apply business rules, and expose normalized APIs to enterprise applications.
Webhooks / outbound callbacksLimitedUPS supports webhook-style tracking notifications for selected events and use cases, but not a universal event stream for every UPS object or operational event.Martini can expose a webhook endpoint, validate and normalize notifications, deduplicate events, and route updates to downstream systems. Scheduled polling can supplement unavailable coverage.
SOAP APIsLegacyOlder UPS shipping, rating, tracking, and address services may use XML and SOAP. REST and OAuth 2.0 are preferred for new integrations where available.Martini can consume SOAP services when an existing implementation requires them, while allowing teams to isolate legacy XML mappings and plan migration to REST.
File / attachment APIsLimitedApplicable UPS APIs can return shipping labels and shipping-related documents, including supported document formats and paperless-document payloads.Martini can preserve binary content and media types, route documents to enterprise applications, and separate document handling from ordinary JSON mapping.
AuthenticationYesCurrent UPS APIs use OAuth 2.0 access tokens, while older integrations may use access-key credentials and account identifiers.Martini can manage OAuth configuration, token acquisition, environment separation, account settings, and sensitive values through secured configuration and secrets.
Bulk / async / batch APIsNot confirmedSome shipment processes may support multiple packages or shipments, but a general-purpose asynchronous bulk API for all UPS resources was not confirmed.Martini can orchestrate controlled batches and scheduled workloads, but the selected UPS product's limits and processing model must be verified before implementation.
Database / analytics accessNoNo direct UPS database-access API or general analytics access API was confirmed.Martini can retrieve operational data through UPS APIs and notifications and persist normalized results in an enterprise database when required.

How UPS exposes data and business events

UPS REST APIs

UPS's current developer platform provides REST APIs for shipping, label generation, tracking, rating, address validation, time in transit, pickup operations, and related services. Payloads are commonly exchanged as JSON, although availability and permissions vary by country, account, and product.

Martini implementation pattern

Martini workflows authenticate with UPS OAuth 2.0, construct provider-specific requests from canonical enterprise data, call the appropriate REST operation, validate the response, and map shipment, tracking, rate, address, or label information to downstream systems.

Implementation sequence

Receive a shipment, rating, tracking, or validation request
Acquire or reuse a valid UPS OAuth access token
Validate required account, address, package, and service fields
Call the applicable UPS REST API
Map and normalize the UPS response
Persist correlation, tracking, and document information

UPS Tracking Notifications

UPS supports webhook-style tracking notifications for selected events and use cases. These notifications should not be treated as a universal event stream, so polling may still be needed for unsupported coverage.

Martini implementation pattern

Martini exposes a controlled webhook endpoint, validates the incoming request according to the applicable UPS mechanism, correlates the notification to a known shipment, and asynchronously updates order, warehouse, customer-service, or notification systems.

Implementation sequence

Receive the UPS tracking notification
Authenticate and validate the request and payload
Correlate the event with a known tracking number
Discard duplicate or stale events
Map the event to the enterprise shipment status model
Acknowledge quickly and process downstream updates

UPS Scheduled Tracking

Scheduled Tracking API requests can supplement webhook-style notifications when a required event or account configuration is not covered by UPS notifications. Tracking responses may include repeated or out-of-order status information.

Martini implementation pattern

Martini schedules a workflow for active shipments, queries UPS for current tracking data, compares the response with the stored status and event timestamps, and writes only meaningful changes to downstream systems.

Implementation sequence

Select active shipments requiring reconciliation
Invoke the UPS Tracking API
Compare returned events with stored status data
Apply timestamp and status-ordering rules
Write changed tracking information to target systems
Record completion and retry transient failures

UPS SOAP and XML Services

UPS historically provided XML- and SOAP-based shipping, rating, tracking, and address services. These interfaces may remain in existing enterprise implementations but are legacy relative to current REST APIs and OAuth 2.0.

Martini implementation pattern

Martini can consume a required UPS SOAP service, map XML request and response structures, isolate legacy credentials and transformations, and expose a stable internal API so downstream systems are not coupled to the SOAP contract.

Implementation sequence

Identify the required legacy UPS SOAP operation
Configure the SOAP endpoint and credentials securely
Map canonical data to the UPS XML request
Call the service and parse the XML response
Translate SOAP faults and business errors
Return normalized data or route the failure for remediation

UPS Labels and Documents

Applicable UPS shipping APIs can return labels and shipping-related documents, including paperless-document payloads for supported scenarios. Formats, country availability, and shipment eligibility must be confirmed for the selected service.

Martini implementation pattern

Martini treats label content as a document payload rather than ordinary JSON text, preserves the media type and correlation identifiers, and routes the result to the source, warehouse, or document-management process.

Implementation sequence

Request a label or document with the shipment operation
Receive the document content and media type
Validate that the response matches the expected shipment
Store or stream the binary content to the target
Associate the document with the shipment and package
Route invalid or unavailable documents for operational review

Common UPS integration patterns

Pattern 1: Create shipments and return labels

When to use this pattern

Use this pattern when an order, fulfillment, or warehouse application needs UPS service selection, shipment creation, tracking identifiers, and label generation. It is appropriate for synchronous API-led fulfillment with durable duplicate protection.

Integration direction
Shopify
Martini
UPS
Example Mapping
UPS FieldCanonical FieldTarget Field
Shipment.ShipTo.AddressdeliveryAddressUPS ShipmentRequest.ShipTo.Address
Package.WeightpackageWeightUPS Package.PackageWeight
Shipment.Service.CodecarrierServiceUPS ShipmentRequest.Service.Code
Label.ContentshippingLabelShopify fulfillment label
Martini implementation pattern

A Martini API receives fulfillment data, validates address, package, billing, and service fields, optionally calls rating or address validation, and then creates the UPS shipment. The workflow stores an order or fulfillment key before returning tracking and label data, and routes transient failures to controlled retries without blindly repeating shipment creation.

Martini capabilities used
  • APIs
  • workflows
  • API consumption
  • data mapping
  • business rules
  • secrets management
  • error handling

Pattern 2: Synchronize UPS tracking to enterprise systems

When to use this pattern

Use this pattern to keep orders, warehouse processes, customer-service applications, and notifications aligned with UPS delivery progress. Combine selected UPS notifications with scheduled reconciliation when webhook coverage is incomplete.

Integration direction
UPS
Martini
Salesforce
Example Mapping
UPS FieldCanonical FieldTarget Field
TrackingNumbershipmentTrackingIdSalesforce Shipment.TrackingNumber
Activity.StatusdeliveryStatusSalesforce Order.ShippingStatus
Activity.DateTimestatusTimestampSalesforce Shipment.LastEventTime
Exception.DescriptiondeliveryExceptionSalesforce Case.Description
Martini implementation pattern

Martini exposes a notification endpoint and runs a scheduled tracking workflow for active shipments. It validates and deduplicates events, applies timestamp ordering, enriches the status with stored order context, and updates target systems with retry and dead-letter handling for failures.

Martini capabilities used
  • webhooks
  • scheduler triggers
  • workflows
  • data mapping
  • idempotency rules
  • error handling
  • monitoring

Pattern 3: Return UPS rates during checkout

When to use this pattern

Use this pattern when a commerce or sales application needs UPS shipping services, charges, currencies, surcharges, and delivery estimates before order submission.

Integration direction
Shopify
Martini
UPS
Shopify
Example Mapping
UPS FieldCanonical FieldTarget Field
RateRequest.ShipTodestinationAddressUPS RateRequest.ShipTo
Package.WeighttotalWeightUPS RateRequest.Package.Weight
Rate.Service.CodeserviceCodeShopify deliveryOption.code
Rate.TotalChargesshippingPriceShopify deliveryOption.price
Martini implementation pattern

Martini receives checkout origin, destination, package, and service requirements, validates the request, calls the UPS rating API, filters or selects eligible services according to business rules, and returns a normalized rate response. The workflow distinguishes invalid inputs from temporary UPS failures so checkout behavior remains predictable.

Martini capabilities used
  • APIs
  • API consumption
  • data mapping
  • transformations
  • business rules
  • validation
  • error handling

Pattern 4: Validate addresses and manage delivery exceptions

When to use this pattern

Use this pattern when address quality must be checked before shipment creation and later UPS delivery exceptions must be routed to customer-service or order-management teams.

Integration direction
NetSuite
Martini
UPS
Zendesk
Example Mapping
UPS FieldCanonical FieldTarget Field
Address.PostalCodepostalCodeUPS AddressValidationRequest.PostalCode
Address.CountryCodecountryCodeUPS AddressValidationRequest.CountryCode
Tracking.ExceptionexceptionReasonZendesk Ticket.Description
Tracking.EstimatedDeliveryestimatedDeliveryDateNetSuite fulfillment.estimatedDelivery
Martini implementation pattern

A Martini workflow validates addresses before shipment creation and returns actionable validation results to the source application. A separate notification or polling workflow correlates tracking exceptions to the shipment, applies severity and escalation rules, and updates Zendesk and NetSuite with retryable integration failures separated from business exceptions.

Martini capabilities used
  • workflows
  • API consumption
  • data mapping
  • validation
  • conditional routing
  • error handling
  • scheduled synchronization

Applications commonly integrated with UPS

UPS can be integrated with order, commerce, ERP, warehouse, and customer-service applications through Martini workflows and APIs. The following are typical enterprise architecture patterns rather than evidence of dedicated UPS integrations maintained by each application vendor.

Application Scenario Direction Martini Pattern
Shopify Create shipments, obtain labels and tracking numbers, and update fulfillment status for online orders. Shopify → Martini → UPS Expose a Martini API for fulfillment requests, validate order and package data, call UPS rating and shipping APIs, then return tracking and label data to Shopify. Process subsequent UPS notifications or polling results to update fulfillment status.
Salesforce Associate tracking information, delivery exceptions, and shipment status with Accounts, Contacts, Cases, or Orders. UPS → Martini → Salesforce Receive UPS notifications or scheduled tracking results, normalize shipment status and exception data, and update Salesforce through an API workflow. Shipment requests can flow from Salesforce through Martini to UPS.
NetSuite Create shipments from sales orders or item fulfillments and write labels, tracking numbers, and freight information back to NetSuite. NetSuite → Martini → UPS Trigger a workflow from a NetSuite fulfillment process, validate the package and address, call UPS shipping services, persist the shipment correlation key, and return tracking and label details to NetSuite.
SAP S/4HANA Support outbound delivery execution, carrier selection, label generation, and shipment tracking. SAP S/4HANA → Martini → UPS Orchestrate delivery data from SAP to UPS, apply service and package rules, preserve returned documents, and reconcile UPS tracking updates back into SAP.
Oracle Fusion Cloud ERP Synchronize fulfillment and shipping information with UPS and return tracking data to order and logistics processes. Oracle Fusion Cloud ERP → Martini → UPS Use Martini APIs and workflows to transform Oracle fulfillment data into UPS requests, handle OAuth credentials and transient errors, and map tracking and label responses back to Oracle.
Microsoft Dynamics 365 Generate labels and tracking information for sales orders, shipments, and fulfillment processes. Microsoft Dynamics 365 → Martini → UPS Receive shipment requests from Dynamics 365, validate address and package fields, call UPS services, and update the originating shipment with tracking, service, and document information.
Manhattan Active WM Send package and shipment information to UPS and receive tracking or delivery updates for warehouse operations. Manhattan Active WM → Martini → UPS Use a warehouse-triggered workflow for shipment creation and a webhook or scheduled reconciliation workflow for tracking updates, with idempotency checks around label generation.
Zendesk Provide customer-service agents with tracking status and delivery exceptions. UPS → Martini → Zendesk Normalize UPS tracking events in Martini, correlate them to orders or customer references, and update Zendesk tickets or customer context through its APIs.

How to build a UPS integration in Martini

Objective

Configure UPS OAuth 2.0 and account-specific settings without embedding secrets in workflow payloads. Keep test and production credentials, country settings, currencies, and measurement systems separate.

Instructions in Martini

  • Register or configure the UPS Developer Portal application
  • Store client credentials, account numbers, and tokens in environment-specific secrets
  • Configure separate test and production endpoints and settings
  • Validate the required UPS permissions for each operation

Objective

Select an API request, UPS tracking notification, or scheduled reconciliation trigger based on the required business process and available UPS event coverage.

Instructions in Martini

  • Use a Martini API for shipment, rating, or validation requests
  • Expose a webhook endpoint for supported UPS tracking notifications
  • Use a scheduler for active-shipment tracking reconciliation
  • Use a workflow trigger for internal fulfillment events

Objective

Receive enterprise shipment data or retrieve current UPS status and service information with the appropriate REST or, where necessary, legacy SOAP operation.

Instructions in Martini

  • Validate request structure and required fields
  • Acquire or reuse a valid UPS OAuth token
  • Call the selected UPS API or consume the supported notification
  • Capture correlation identifiers and provider response metadata

Objective

Coordinate validation, provider calls, transformations, target updates, document handling, and exception paths in a maintainable Martini workflow.

Instructions in Martini

  • Sequence address, rate, shipping, and tracking operations as required
  • Branch on service availability, validation errors, and transient failures
  • Preserve label content as a document payload
  • Use reusable logic for correlation and status normalization

Objective

Translate UPS shipment, package, rate, address, tracking, and label structures into canonical enterprise models and target application schemas.

Instructions in Martini

  • Map nested UPS JSON or XML structures to canonical fields
  • Normalize service codes, statuses, timestamps, currencies, and units
  • Preserve tracking and shipment identifiers
  • Map binary labels with their correct media types

Objective

Prevent invalid or duplicate operational actions and determine how services, statuses, exceptions, and retries should be handled.

Instructions in Martini

  • Validate addresses, package dimensions, weight, billing, and service values
  • Use order, fulfillment, or shipment keys for idempotency
  • Reject stale or duplicate tracking events
  • Apply service-selection and exception-escalation rules

Common UPS data objects used in integrations

ObjectTypical UseCommon target systemsMartini handling
ShipmentShipment creation, service selection, ship-from and ship-to details, billing, and label generation.NetSuite, SAP S/4HANA, Oracle Fusion Cloud ERP, Microsoft Dynamics 365, ShopifyMartini validates shipment inputs, applies service and account rules, calls UPS shipping APIs, and stores correlation and response data for idempotency.
PackageIndividual package dimensions, weight, packaging, and tracking information within a shipment.Manhattan Active WM, SAP S/4HANA, NetSuite, ShopifyMartini maps package structures, validates required measurements and packaging values, and preserves package-to-shipment relationships.
Tracking NumberLookup key for package status, scans, estimated delivery, and delivery events.Salesforce, Zendesk, Shopify, order-management systemsMartini uses tracking numbers for webhook correlation or scheduled polling, deduplicates status events, and updates downstream records.
RateShipping service, price, currency, delivery estimate, and surcharge information.Shopify, sales applications, order-management systemsMartini calls rating APIs, normalizes service and charge structures, applies selection rules, and returns rates through an API.
AddressOrigin, destination, billing, and validation data for shipping and address services.Shopify, Salesforce, SAP S/4HANA, Oracle Fusion Cloud ERPMartini validates country, postal, and address fields before shipment creation and maps UPS validation results to the source schema.
LabelShipping label or document generated for a package or shipment.Shopify, NetSuite, warehouse systems, SAP S/4HANAMartini preserves returned binary content and media type, then routes the document to the requesting application or document workflow.

Authentication and security considerations

OAuth 2.0 and secrets

Current UPS APIs generally use OAuth 2.0 access tokens obtained through a registered UPS Developer Portal application. Store client credentials, account numbers, token configuration, and environment-specific settings in Martini secrets and configuration rather than workflow payloads.

Environment and account controls

  • Separate UPS test and production configuration.
  • Restrict access to client secrets and account-specific settings.
  • Confirm permissions, country availability, and account authorization for each UPS service.
  • Treat legacy access-key credentials as sensitive and transitional where they remain necessary.

Webhook protection

Validate the documented authentication or validation mechanism for UPS webhook-style notifications, correlate requests to known shipments, prevent replay or duplicate processing where applicable, and acknowledge quickly before longer downstream processing.

Operational considerations for UPS integrations

Rate limits and retries

Check UPS quotas and traffic policies for the relevant application and account. Apply controlled backoff for throttling and temporary service failures, while returning validation and authorization errors for correction instead of retrying them indefinitely.

Idempotency and shipment safety

Shipment creation is operationally sensitive because a lost response can hide a successful request. Persist order, fulfillment, or shipment keys with UPS identifiers before allowing a retry, and distinguish duplicate requests from transient failures.

Data and schema handling

  • Handle nested collections and multiple rates or packages without assuming the first result is correct.
  • Validate addresses, country codes, dimensions, weight, service, billing, and customs data before shipment creation.
  • Preserve label binary content and its media type rather than treating it as ordinary JSON.
  • Apply timestamp and status-ordering rules to repeated or out-of-order tracking events.
  • Version mappings for API changes, service codes, enumerations, and regional differences.

Testing and monitoring

Test test-environment credentials, regional service availability, label formats, duplicate scenarios, timeout behavior, and webhook coverage before production rollout. Monitor workflow logs, API failures, reconciliation gaps, and documents that cannot be delivered to target systems.

Why use Martini instead of scripts or point-to-point integrations?

Orchestration beyond point-to-point calls

Martini centralizes UPS API calls, webhook intake, scheduled reconciliation, validation, transformations, downstream updates, and exception handling in maintainable workflows rather than scattering logic across scripts and applications.

Stable enterprise contracts

Martini can expose an internal API façade that shields consuming systems from UPS-specific payloads, OAuth details, service codes, document formats, and legacy SOAP dependencies.

Operational reliability

  • Apply reusable mappings, business rules, idempotency checks, and controlled retries.
  • Combine selected UPS notifications with scheduled polling when event coverage is incomplete.
  • Separate business validation errors from transient provider failures.
  • Keep credentials and regional configuration outside deployed workflow logic.

Frequently asked questions

How can UPS be integrated with enterprise systems?

UPS can be integrated through its current REST APIs for shipping, label generation, tracking, rating, address validation, time in transit, pickup, and related operations. OAuth 2.0 is the preferred authentication approach for current APIs. Selected tracking notifications can be received through webhook-style callbacks, while scheduled Tracking API requests can supplement events. Legacy SOAP/XML services may support existing implementations.

Can Martini integrate with UPS?

Yes. Martini can consume UPS REST APIs, receive supported UPS tracking notifications through an exposed endpoint, orchestrate scheduled tracking reconciliation, and consume legacy SOAP/XML services when required. It can map UPS data, handle OAuth configuration, preserve labels, and update enterprise applications.

Do I need a connector to integrate UPS with Martini?

No. A dedicated UPS connector is not required. Martini can integrate using UPS's confirmed native mechanisms, including REST APIs, OAuth 2.0, selected webhook-style notifications, shipping documents, and legacy SOAP/XML services where necessary.

Is there any extra Lonti cost to integrate UPS with Martini?

Lonti does not charge an additional per-connector or per-vendor fee to integrate UPS. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from UPS, cloud infrastructure, or other third-party systems based on subscriptions, API usage, shipping activity, and deployment model.

Which UPS integration methods should a new implementation use?

New implementations should generally use UPS REST APIs with OAuth 2.0. Use the Shipping, Rating, Tracking, Address Validation, and related APIs required by the process. SOAP/XML should primarily be retained for existing integrations or capabilities not yet available through the applicable REST service.

Are UPS webhooks available for every tracking event?

No. UPS webhook-style tracking notifications are available for selected events and use cases rather than every UPS object or operational event. Martini can receive supported notifications and supplement them with scheduled Tracking API polling and reconciliation.

How does synchronization and duplicate handling work?

Martini can combine event-driven notifications with scheduled tracking queries, compare event timestamps, and update only meaningful changes. Shipment creation should use a durable order, fulfillment, or shipment key and store the resulting UPS identifiers so a timeout or retry does not blindly create a duplicate shipment.

Can Martini expose an API façade for UPS?

Yes. Martini can expose an internal REST API that presents a stable enterprise contract for rating, shipment creation, tracking, address validation, or label retrieval while hiding UPS-specific request formats, authentication, mappings, and error handling from consuming applications.

Related Martini documentation

UPS APIs

Events

Workflows

Security

Operations

Connect UPS with Martini

Use Martini to orchestrate UPS shipping, rating, tracking, address validation, notifications, and label workflows across your enterprise systems.

EXPLORE MARTINI
BOOK A DEMO