MACRO NEPAL
Shipping and Logistics: Integrating UPS APIs with Java Applications
awiskar acharya
November 22, 2025
3:47 pm

The UPS Developer Kit provides comprehensive APIs for shipping, tracking, rates, and address validation. Java applications can leverage these APIs to build powerful logistics solutions, e-commerce shipping integrations, and supply chain management systems. Let's explore how to implement UPS API integrations in Java.

Why UPS APIs for Java Applications?

Key integration scenarios:

  • E-commerce Shipping - Calculate rates and create shipments
  • Order Fulfillment - Automate shipping label generation
  • Package Tracking - Real-time shipment tracking
  • Address Validation - Verify shipping addresses
  • Supply Chain Visibility - Monitor logistics operations

UPS API Configuration and Authentication

1. UPS Configuration

@Configuration
@ConfigurationProperties(prefix = "ups")
@Data
public class UPSConfig {
private String clientId;
private String clientSecret;
private String baseUrl = "https://wwwcie.ups.com"; // Sandbox
// private String baseUrl = "https://onlinetools.ups.com"; // Production
private String accountNumber;
private String userId;
private String password;
private int timeoutSeconds = 30;
public String getAccessTokenUrl() {
return baseUrl + "/security/v1/oauth/token";
}
public String getShippingUrl() {
return baseUrl + "/api/shipments/v1/ship";
}
public String getRatingUrl() {
return baseUrl + "/api/rating/v1/Shop";
}
public String getTrackingUrl() {
return baseUrl + "/api/track/v1/details";
}
public String getAddressValidationUrl() {
return baseUrl + "/api/addressvalidation/v1/1";
}
}

2. OAuth Authentication Service

@Service
@Slf4j
public class UPSAuthService {
private final UPSConfig config;
private final OkHttpClient httpClient;
private final ObjectMapper objectMapper;
public UPSAuthService(UPSConfig config) {
this.config = config;
this.httpClient = new OkHttpClient();
this.objectMapper = new ObjectMapper();
}
public UPSAccessToken getAccessToken() throws UPSApiException {
try {
String credentials = Credentials.basic(config.getClientId(), config.getClientSecret());
FormBody formBody = new FormBody.Builder()
.add("grant_type", "client_credentials")
.build();
Request request = new Request.Builder()
.url(config.getAccessTokenUrl())
.header("Authorization", credentials)
.header("Content-Type", "application/x-www-form-urlencoded")
.post(formBody)
.build();
Response response = httpClient.newCall(request).execute();
if (!response.isSuccessful()) {
throw new UPSApiException("Failed to get access token: " + response.code());
}
String responseBody = response.body().string();
UPSAccessToken token = objectMapper.readValue(responseBody, UPSAccessToken.class);
token.setIssuedAt(Instant.now());
log.info("UPS access token obtained, expires in: {} seconds", token.getExpiresIn());
return token;
} catch (Exception e) {
throw new UPSApiException("UPS authentication failed", e);
}
}
@Data
public static class UPSAccessToken {
private String accessToken;
private String tokenType;
private Integer expiresIn;
private String issuedAt;
private String scope;
private Instant issuedAtInstant;
public void setIssuedAt(Instant issuedAt) {
this.issuedAtInstant = issuedAt;
}
public boolean isExpired() {
if (issuedAtInstant == null || expiresIn == null) {
return true;
}
return issuedAtInstant.plusSeconds(expiresIn - 300).isBefore(Instant.now()); // 5 min buffer
}
public Instant getExpiryTime() {
return issuedAtInstant != null ? issuedAtInstant.plusSeconds(expiresIn) : null;
}
}
}

Core UPS API Client

1. Base UPS API Client

@Service
@Slf4j
public class UPSApiClient {
private final UPSConfig config;
private final UPSAuthService authService;
private final OkHttpClient httpClient;
private final ObjectMapper objectMapper;
private UPSAuthService.UPSAccessToken currentToken;
public UPSApiClient(UPSConfig config, UPSAuthService authService) {
this.config = config;
this.authService = authService;
this.objectMapper = new ObjectMapper();
this.objectMapper.configure(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES, false);
this.httpClient = new OkHttpClient.Builder()
.addInterceptor(new UPSAuthInterceptor())
.addInterceptor(new HttpLoggingInterceptor(log::info).setLevel(HttpLoggingInterceptor.Level.BASIC))
.connectTimeout(config.getTimeoutSeconds(), TimeUnit.SECONDS)
.readTimeout(config.getTimeoutSeconds(), TimeUnit.SECONDS)
.build();
}
// Generic API call with authentication
protected <T> T executePost(String endpoint, Object request, Class<T> responseType) throws UPSApiException {
ensureValidToken();
try {
String jsonBody = objectMapper.writeValueAsString(request);
Request httpRequest = new Request.Builder()
.url(endpoint)
.header("Authorization", "Bearer " + currentToken.getAccessToken())
.header("Content-Type", "application/json")
.header("transId", UUID.randomUUID().toString())
.header("transactionSrc", "your-application-name")
.post(RequestBody.create(jsonBody, MediaType.parse("application/json")))
.build();
Response response = httpClient.newCall(httpRequest).execute();
if (!response.isSuccessful()) {
handleErrorResponse(response, endpoint);
}
String responseBody = response.body().string();
return objectMapper.readValue(responseBody, responseType);
} catch (Exception e) {
throw new UPSApiException("UPS API request failed: " + endpoint, e);
}
}
protected <T> T executeGet(String endpoint, Class<T> responseType) throws UPSApiException {
ensureValidToken();
try {
Request httpRequest = new Request.Builder()
.url(endpoint)
.header("Authorization", "Bearer " + currentToken.getAccessToken())
.header("Content-Type", "application/json")
.get()
.build();
Response response = httpClient.newCall(httpRequest).execute();
if (!response.isSuccessful()) {
handleErrorResponse(response, endpoint);
}
String responseBody = response.body().string();
return objectMapper.readValue(responseBody, responseType);
} catch (Exception e) {
throw new UPSApiException("UPS API request failed: " + endpoint, e);
}
}
private void ensureValidToken() throws UPSApiException {
if (currentToken == null || currentToken.isExpired()) {
log.info("UPS access token expired or missing, obtaining new token");
currentToken = authService.getAccessToken();
}
}
private void handleErrorResponse(Response response, String endpoint) throws IOException, UPSApiException {
int code = response.code();
String body = response.body() != null ? response.body().string() : "No response body";
log.error("UPS API error - Status: {}, Endpoint: {}, Body: {}", code, endpoint, body);
try {
UPSError error = objectMapper.readValue(body, UPSError.class);
throw new UPSApiException("UPS API Error: " + error.getResponse().getErrors().get(0).getMessage(), code);
} catch (Exception e) {
throw new UPSApiException("UPS API error - Status: " + code + ", Endpoint: " + endpoint, code);
}
}
// Authentication interceptor for automatic token refresh
private class UPSAuthInterceptor implements Interceptor {
@Override
public Response intercept(Chain chain) throws IOException {
Request originalRequest = chain.request();
try {
ensureValidToken();
} catch (UPSApiException e) {
throw new IOException("Failed to obtain UPS access token", e);
}
Request authenticatedRequest = originalRequest.newBuilder()
.header("Authorization", "Bearer " + currentToken.getAccessToken())
.build();
return chain.proceed(authenticatedRequest);
}
}
}

Shipping Service

1. Shipment Creation and Management

@Service
@Slf4j
public class UPSShipmentService extends UPSApiClient {
public UPSShipmentService(UPSConfig config, UPSAuthService authService) {
super(config, authService);
}
public ShipmentResponse createShipment(ShipmentRequest shipmentRequest) throws UPSApiException {
return executePost(config.getShippingUrl(), shipmentRequest, ShipmentResponse.class);
}
public VoidResponse voidShipment(String shipmentIdentificationNumber) throws UPSApiException {
VoidShipmentRequest voidRequest = new VoidShipmentRequest();
voidRequest.setVoidShipment(createVoidShipment(shipmentIdentificationNumber));
String endpoint = config.getShippingUrl().replace("/ship", "/void");
return executePost(endpoint, voidRequest, VoidResponse.class);
}
public ShipmentResponse createShipmentWithDetails(Address fromAddress, Address toAddress, 
PackageDetails packageDetails, 
ShipmentOptions options) throws UPSApiException {
ShipmentRequest request = createShipmentRequest(fromAddress, toAddress, packageDetails, options);
return createShipment(request);
}
public byte[] getShippingLabel(String shipmentIdentificationNumber) throws UPSApiException {
try {
// First get shipment details
ShipmentResponse shipment = getShipment(shipmentIdentificationNumber);
// Extract label URL from response
String labelUrl = shipment.getShipmentResponse().getShipmentResults()
.getPackageResults().get(0).getShippingLabel().getGraphicImage();
// Download label image
return downloadLabelImage(labelUrl);
} catch (Exception e) {
throw new UPSApiException("Failed to get shipping label", e);
}
}
private ShipmentRequest createShipmentRequest(Address fromAddress, Address toAddress,
PackageDetails packageDetails, ShipmentOptions options) {
ShipmentRequest request = new ShipmentRequest();
Shipment shipment = new Shipment();
// Set shipper information
shipment.setShipper(createParty(fromAddress, options.getShipperName(), options.getShipperNumber()));
// Set ship to information
shipment.setShipTo(createParty(toAddress, options.getReceiverName(), null));
// Set service
Service service = new Service();
service.setCode(options.getServiceCode());
service.setDescription(options.getServiceDescription());
shipment.setService(service);
// Set package
shipment.setPackage(createPackage(packageDetails));
// Set payment information
shipment.setPaymentInformation(createPaymentInformation());
request.setShipment(shipment);
// Set request options
Request requestOptions = new Request();
requestOptions.setRequestOption("validate");
request.setRequest(requestOptions);
return request;
}
private Party createParty(Address address, String name, String shipperNumber) {
Party party = new Party();
party.setName(name);
party.setAddress(address);
if (shipperNumber != null) {
party.setShipperNumber(shipperNumber);
}
return party;
}
private Package createPackage(PackageDetails details) {
Package pkg = new Package();
// Packaging type
PackagingType packagingType = new PackagingType();
packagingType.setCode("02"); // Customer supplied package
packagingType.setDescription("Package");
pkg.setPackagingType(packagingType);
// Package weight
PackageWeight weight = new PackageWeight();
weight.setWeight(String.valueOf(details.getWeightLbs()));
UnitOfMeasurement uom = new UnitOfMeasurement();
uom.setCode("LBS");
weight.setUnitOfMeasurement(uom);
pkg.setPackageWeight(weight);
// Package dimensions
Dimensions dimensions = new Dimensions();
dimensions.setLength(String.valueOf(details.getLengthInches()));
dimensions.setWidth(String.valueOf(details.getWidthInches()));
dimensions.setHeight(String.valueOf(details.getHeightInches()));
UnitOfMeasurement dimUom = new UnitOfMeasurement();
dimUom.setCode("IN");
dimensions.setUnitOfMeasurement(dimUom);
pkg.setDimensions(dimensions);
return pkg;
}
private PaymentInformation createPaymentInformation() {
PaymentInformation paymentInfo = new PaymentInformation();
ShipmentCharge shipmentCharge = new ShipmentCharge();
// Bill shipper
BillShipper billShipper = new BillShipper();
billShipper.setAccountNumber(config.getAccountNumber());
shipmentCharge.setBillShipper(billShipper);
// Charge type
shipmentCharge.setType("01"); // Transportation
paymentInfo.setShipmentCharge(new ShipmentCharge[]{shipmentCharge});
return paymentInfo;
}
private VoidShipment createVoidShipment(String shipmentIdentificationNumber) {
VoidShipment voidShipment = new VoidShipment();
voidShipment.setShipmentIdentificationNumber(shipmentIdentificationNumber);
return voidShipment;
}
private byte[] downloadLabelImage(String labelUrl) throws Exception {
Request request = new Request.Builder()
.url(labelUrl)
.get()
.build();
Response response = httpClient.newCall(request).execute();
if (!response.isSuccessful()) {
throw new UPSApiException("Failed to download label image: " + response.code());
}
return response.body().bytes();
}
}

Rating Service

1. Shipping Rates and Service Options

@Service
@Slf4j
public class UPSRatingService extends UPSApiClient {
public UPSRatingService(UPSConfig config, UPSAuthService authService) {
super(config, authService);
}
public RatingResponse getShippingRates(RatingRequest ratingRequest) throws UPSApiException {
return executePost(config.getRatingUrl(), ratingRequest, RatingResponse.class);
}
public List<ShippingOption> getAvailableServices(Address fromAddress, Address toAddress, 
PackageDetails packageDetails) throws UPSApiException {
RatingRequest ratingRequest = createRatingRequest(fromAddress, toAddress, packageDetails);
RatingResponse response = getShippingRates(ratingRequest);
return extractShippingOptions(response);
}
public ShippingOption getCheapestService(Address fromAddress, Address toAddress,
PackageDetails packageDetails) throws UPSApiException {
List<ShippingOption> options = getAvailableServices(fromAddress, toAddress, packageDetails);
return options.stream()
.min(Comparator.comparing(ShippingOption::getTotalCharges))
.orElseThrow(() -> new UPSApiException("No shipping options available"));
}
public ShippingOption getFastestService(Address fromAddress, Address toAddress,
PackageDetails packageDetails) throws UPSApiException {
List<ShippingOption> options = getAvailableServices(fromAddress, toAddress, packageDetails);
return options.stream()
.min(Comparator.comparing(ShippingOption::getTransitDays))
.orElseThrow(() -> new UPSApiException("No shipping options available"));
}
private RatingRequest createRatingRequest(Address fromAddress, Address toAddress,
PackageDetails packageDetails) {
RatingRequest request = new RatingRequest();
Request requestOptions = new Request();
requestOptions.setRequestOption("Shop");
request.setRequest(requestOptions);
Shipment shipment = new Shipment();
// Shipper address
shipment.setShipper(createAddressParty(fromAddress));
// Ship to address
shipment.setShipTo(createAddressParty(toAddress));
// Package
shipment.setPackage(createRatePackage(packageDetails));
request.setShipment(shipment);
return request;
}
private List<ShippingOption> extractShippingOptions(RatingResponse response) {
List<ShippingOption> options = new ArrayList<>();
if (response.getRateResponse() != null && 
response.getRateResponse().getRatedShipment() != null) {
for (RatedShipment ratedShipment : response.getRateResponse().getRatedShipment()) {
ShippingOption option = new ShippingOption();
option.setServiceCode(ratedShipment.getService().getCode());
option.setServiceName(ratedShipment.getService().getDescription());
option.setTotalCharges(new BigDecimal(ratedShipment.getTotalCharges().getMonetaryValue()));
option.setCurrency(ratedShipment.getTotalCharges().getCurrencyCode());
option.setTransitDays(ratedShipment.getGuaranteedDelivery().getBusinessDaysInTransit());
option.setDeliveryDate(ratedShipment.getGuaranteedDelivery().getDeliveryByDate());
options.add(option);
}
}
return options;
}
}

Tracking Service

1. Package Tracking and Status

@Service
@Slf4j
public class UPSTrackingService extends UPSApiClient {
public UPSTrackingService(UPSConfig config, UPSAuthService authService) {
super(config, authService);
}
public TrackingResponse trackPackage(String trackingNumber) throws UPSApiException {
String endpoint = config.getTrackingUrl() + "/" + trackingNumber;
return executeGet(endpoint, TrackingResponse.class);
}
public TrackingResponse trackPackageWithDetail(String trackingNumber) throws UPSApiException {
String endpoint = config.getTrackingUrl() + "/" + trackingNumber + "?locale=en_US";
return executeGet(endpoint, TrackingResponse.class);
}
public List<PackageStatus> getActiveShipments(List<String> trackingNumbers) throws UPSApiException {
List<PackageStatus> statuses = new ArrayList<>();
for (String trackingNumber : trackingNumbers) {
try {
TrackingResponse response = trackPackage(trackingNumber);
PackageStatus status = extractPackageStatus(response, trackingNumber);
statuses.add(status);
} catch (UPSApiException e) {
log.warn("Failed to track package: {}", trackingNumber, e);
// Continue with other packages
}
}
return statuses;
}
public Map<String, PackageStatus> getShipmentStatusMap(List<String> trackingNumbers) throws UPSApiException {
return getActiveShipments(trackingNumbers).stream()
.collect(Collectors.toMap(PackageStatus::getTrackingNumber, Function.identity()));
}
public List<PackageStatus> findDelayedShipments(List<String> trackingNumbers) throws UPSApiException {
return getActiveShipments(trackingNumbers).stream()
.filter(status -> "DELAYED".equals(status.getStatus()) || status.isDelayed())
.collect(Collectors.toList());
}
public List<PackageStatus> findDeliveredShipments(List<String> trackingNumbers) throws UPSApiException {
return getActiveShipments(trackingNumbers).stream()
.filter(PackageStatus::isDelivered)
.collect(Collectors.toList());
}
private PackageStatus extractPackageStatus(TrackingResponse response, String trackingNumber) {
PackageStatus status = new PackageStatus();
status.setTrackingNumber(trackingNumber);
if (response.getTrackResponse() != null && 
!response.getTrackResponse().getShipment().isEmpty()) {
Shipment shipment = response.getTrackResponse().getShipment().get(0);
status.setService(shipment.getService().getDescription());
if (!shipment.getPackage().isEmpty()) {
Package pkg = shipment.getPackage().get(0);
status.setStatus(pkg.getActivity().get(0).getStatus().getDescription());
status.setLastUpdate(pkg.getActivity().get(0).getDate() + " " + pkg.getActivity().get(0).getTime());
status.setDeliveryDate(pkg.getDeliveryDate());
status.setSignedBy(pkg.getSignedForByName());
}
}
return status;
}
}

Address Validation Service

1. Address Verification

@Service
@Slf4j
public class UPSAddressService extends UPSApiClient {
public UPSAddressService(UPSConfig config, UPSAuthService authService) {
super(config, authService);
}
public AddressValidationResponse validateAddress(Address address) throws UPSApiException {
AddressValidationRequest request = createAddressValidationRequest(address);
return executePost(config.getAddressValidationUrl(), request, AddressValidationResponse.class);
}
public AddressValidationResult validateAndCorrectAddress(Address address) throws UPSApiException {
AddressValidationResponse response = validateAddress(address);
return extractValidationResult(response);
}
public boolean isAddressValid(Address address) throws UPSApiException {
AddressValidationResponse response = validateAddress(address);
return response.getXAVResponse().getValidAddressIndicator() != null;
}
public List<Address> getAddressSuggestions(Address address) throws UPSApiException {
AddressValidationResponse response = validateAddress(address);
return extractAddressSuggestions(response);
}
private AddressValidationRequest createAddressValidationRequest(Address address) {
AddressValidationRequest request = new AddressValidationRequest();
Request requestOptions = new Request();
requestOptions.setRequestOption("1"); // Address validation
request.setRequest(requestOptions);
AddressKeyFormat addressKeyFormat = new AddressKeyFormat();
addressKeyFormat.setConsigneeName(address.getConsigneeName());
addressKeyFormat.setAddressLine(address.getAddressLine());
addressKeyFormat.setPoliticalDivision2(address.getCity());
addressKeyFormat.setPoliticalDivision1(address.getState());
addressKeyFormat.setPostcodePrimaryLow(address.getPostalCode());
addressKeyFormat.setCountryCode(address.getCountryCode());
request.setAddressKeyFormat(new AddressKeyFormat[]{addressKeyFormat});
return request;
}
private AddressValidationResult extractValidationResult(AddressValidationResponse response) {
AddressValidationResult result = new AddressValidationResult();
if (response.getXAVResponse() != null) {
result.setValid(response.getXAVResponse().getValidAddressIndicator() != null);
result.setQualityScore(response.getXAVResponse().getAddressClassification().getCode());
if (response.getXAVResponse().getCandidate() != null) {
List<Address> candidates = Arrays.stream(response.getXAVResponse().getCandidate())
.map(this::mapCandidateToAddress)
.collect(Collectors.toList());
result.setSuggestedAddresses(candidates);
}
}
return result;
}
private List<Address> extractAddressSuggestions(AddressValidationResponse response) {
if (response.getXAVResponse() != null && response.getXAVResponse().getCandidate() != null) {
return Arrays.stream(response.getXAVResponse().getCandidate())
.map(this::mapCandidateToAddress)
.collect(Collectors.toList());
}
return Collections.emptyList();
}
private Address mapCandidateToAddress(Candidate candidate) {
Address address = new Address();
address.setAddressLine(candidate.getAddressLine());
address.setCity(candidate.getPoliticalDivision2());
address.setState(candidate.getPoliticalDivision1());
address.setPostalCode(candidate.getPostcodePrimaryLow());
address.setCountryCode(candidate.getCountryCode());
address.setQuality(candidate.getAddressQuality());
return address;
}
}

Data Models

1. Core UPS Data Models

@Data
public class ShipmentRequest {
private Request Request;
private Shipment Shipment;
}
@Data
public class Shipment {
private String Description;
private Party Shipper;
private Party ShipTo;
private Party ShipFrom;
private Service Service;
private Package Package;
private PaymentInformation PaymentInformation;
private String ShipmentRatingOptions;
}
@Data
public class Party {
private String Name;
private String AttentionName;
private String ShipperNumber;
private Address Address;
private String PhoneNumber;
}
@Data
public class Address {
private String[] AddressLine;
private String City;
private String State;
private String PostalCode;
private String CountryCode;
private String ConsigneeName;
public String getAddressLine() {
return AddressLine != null && AddressLine.length > 0 ? AddressLine[0] : null;
}
public void setAddressLine(String addressLine) {
this.AddressLine = new String[]{addressLine};
}
}
@Data
public class Package {
private String Description;
private PackagingType PackagingType;
private Dimensions Dimensions;
private PackageWeight PackageWeight;
}
@Data
public class PackageDetails {
private BigDecimal weightLbs;
private BigDecimal lengthInches;
private BigDecimal widthInches;
private BigDecimal heightInches;
private String description;
}
@Data
public class ShipmentOptions {
private String serviceCode;
private String serviceDescription;
private String shipperName;
private String shipperNumber;
private String receiverName;
private boolean saturdayDelivery;
private boolean insurance;
private BigDecimal declaredValue;
}
@Data
public class ShippingOption {
private String serviceCode;
private String serviceName;
private BigDecimal totalCharges;
private String currency;
private Integer transitDays;
private String deliveryDate;
private boolean saturdayDelivery;
}
@Data
public class PackageStatus {
private String trackingNumber;
private String status;
private String service;
private String lastUpdate;
private String deliveryDate;
private String signedBy;
private boolean isDelivered;
private boolean isDelayed;
public boolean isDelivered() {
return "DELIVERED".equalsIgnoreCase(status);
}
public boolean isDelayed() {
return "DELAYED".equalsIgnoreCase(status) || 
(deliveryDate != null && LocalDate.parse(deliveryDate).isBefore(LocalDate.now()));
}
}
@Data
public class AddressValidationResult {
private boolean valid;
private String qualityScore;
private List<Address> suggestedAddresses;
private String validationMessage;
}
// Response models
@Data
public class ShipmentResponse {
private ShipmentResponseWrapper ShipmentResponse;
@Data
public static class ShipmentResponseWrapper {
private Response Response;
private ShipmentResults ShipmentResults;
}
@Data
public static class ShipmentResults {
private String ShipmentIdentificationNumber;
private List<PackageResults> PackageResults;
}
}
@Data
public class RatingResponse {
private RateResponse RateResponse;
@Data
public static class RateResponse {
private List<RatedShipment> RatedShipment;
}
}
@Data
public class TrackingResponse {
private TrackResponse TrackResponse;
@Data
public static class TrackResponse {
private List<Shipment> Shipment;
}
}
@Data
public class UPSError {
private Response response;
@Data
public static class Response {
private List<Error> Errors;
}
@Data
public static class Error {
private String Code;
private String Message;
}
}

REST Controller

1. UPS Integration API

@RestController
@RequestMapping("/api/ups")
@Slf4j
public class UPSController {
private final UPSShipmentService shipmentService;
private final UPSRatingService ratingService;
private final UPSTrackingService trackingService;
private final UPSAddressService addressService;
public UPSController(UPSShipmentService shipmentService,
UPSRatingService ratingService,
UPSTrackingService trackingService,
UPSAddressService addressService) {
this.shipmentService = shipmentService;
this.ratingService = ratingService;
this.trackingService = trackingService;
this.addressService = addressService;
}
@PostMapping("/shipments")
public ResponseEntity<ShipmentResponse> createShipment(@RequestBody CreateShipmentRequest request) {
try {
ShipmentResponse response = shipmentService.createShipmentWithDetails(
request.getFromAddress(),
request.getToAddress(),
request.getPackageDetails(),
request.getOptions()
);
return ResponseEntity.ok(response);
} catch (UPSApiException e) {
log.error("Failed to create shipment", e);
return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
}
}
@PostMapping("/shipments/{shipmentId}/void")
public ResponseEntity<Void> voidShipment(@PathVariable String shipmentId) {
try {
shipmentService.voidShipment(shipmentId);
return ResponseEntity.ok().build();
} catch (UPSApiException e) {
log.error("Failed to void shipment: {}", shipmentId, e);
return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
}
}
@GetMapping("/rates")
public ResponseEntity<List<ShippingOption>> getShippingRates(@RequestBody RateRequest request) {
try {
List<ShippingOption> options = ratingService.getAvailableServices(
request.getFromAddress(),
request.getToAddress(),
request.getPackageDetails()
);
return ResponseEntity.ok(options);
} catch (UPSApiException e) {
log.error("Failed to get shipping rates", e);
return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
}
}
@GetMapping("/tracking/{trackingNumber}")
public ResponseEntity<PackageStatus> trackPackage(@PathVariable String trackingNumber) {
try {
TrackingResponse response = trackingService.trackPackage(trackingNumber);
PackageStatus status = extractPackageStatus(response, trackingNumber);
return ResponseEntity.ok(status);
} catch (UPSApiException e) {
log.error("Failed to track package: {}", trackingNumber, e);
return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
}
}
@PostMapping("/address/validate")
public ResponseEntity<AddressValidationResult> validateAddress(@RequestBody Address address) {
try {
AddressValidationResult result = addressService.validateAndCorrectAddress(address);
return ResponseEntity.ok(result);
} catch (UPSApiException e) {
log.error("Failed to validate address", e);
return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
}
}
@GetMapping("/labels/{shipmentId}")
public ResponseEntity<byte[]> getShippingLabel(@PathVariable String shipmentId) {
try {
byte[] labelData = shipmentService.getShippingLabel(shipmentId);
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.IMAGE_PNG);
headers.setContentDisposition(ContentDisposition.attachment()
.filename("shipping-label-" + shipmentId + ".png")
.build());
return new ResponseEntity<>(labelData, headers, HttpStatus.OK);
} catch (UPSApiException e) {
log.error("Failed to get shipping label: {}", shipmentId, e);
return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
}
}
@PostMapping("/tracking/batch")
public ResponseEntity<Map<String, PackageStatus>> trackMultiplePackages(
@RequestBody List<String> trackingNumbers) {
try {
Map<String, PackageStatus> statusMap = trackingService.getShipmentStatusMap(trackingNumbers);
return ResponseEntity.ok(statusMap);
} catch (UPSApiException e) {
log.error("Failed to track multiple packages", e);
return ResponseEntity.status(HttpStatus.BAD_REQUEST).build();
}
}
private PackageStatus extractPackageStatus(TrackingResponse response, String trackingNumber) {
// Implementation to extract status from TrackingResponse
PackageStatus status = new PackageStatus();
status.setTrackingNumber(trackingNumber);
// ... populate status from response
return status;
}
@Data
public static class CreateShipmentRequest {
private Address fromAddress;
private Address toAddress;
private PackageDetails packageDetails;
private ShipmentOptions options;
}
@Data
public static class RateRequest {
private Address fromAddress;
private Address toAddress;
private PackageDetails packageDetails;
}
}

Error Handling

1. Custom Exceptions

public class UPSApiException extends Exception {
private final Integer statusCode;
public UPSApiException(String message) {
super(message);
this.statusCode = null;
}
public UPSApiException(String message, Integer statusCode) {
super(message);
this.statusCode = statusCode;
}
public UPSApiException(String message, Throwable cause) {
super(message, cause);
this.statusCode = null;
}
public Integer getStatusCode() {
return statusCode;
}
}
@ControllerAdvice
public class UPSExceptionHandler {
@ExceptionHandler(UPSApiException.class)
public ResponseEntity<ErrorResponse> handleUPSApiException(UPSApiException e) {
log.error("UPS API error", e);
ErrorResponse error = new ErrorResponse(
"UPS_API_ERROR",
e.getMessage(),
e.getStatusCode(),
LocalDateTime.now()
);
return ResponseEntity.status(
e.getStatusCode() != null ? HttpStatus.valueOf(e.getStatusCode()) : HttpStatus.INTERNAL_SERVER_ERROR
).body(error);
}
@Data
public static class ErrorResponse {
private final String error;
private final String message;
private final Integer statusCode;
private final LocalDateTime timestamp;
}
}

Configuration

1. Application Properties

# application.yml
ups:
client-id: ${UPS_CLIENT_ID}
client-secret: ${UPS_CLIENT_SECRET}
base-url: https://wwwcie.ups.com
account-number: ${UPS_ACCOUNT_NUMBER}
user-id: ${UPS_USER_ID}
password: ${UPS_PASSWORD}
timeout-seconds: 30

Best Practices

  1. Token Management - Implement token caching and refresh logic
  2. Error Handling - Handle UPS-specific error codes and rate limits
  3. Retry Logic - Implement retry with exponential backoff for transient failures
  4. Logging - Comprehensive logging for debugging and audit trails
  5. Validation - Validate all inputs before sending to UPS APIs
  6. Batch Operations - Use batch processing for multiple shipments or tracking requests
  7. Security - Secure API credentials and use HTTPS for all communications

Conclusion

Integrating UPS APIs with Java applications enables powerful shipping and logistics automation. By implementing the patterns shown here, Java developers can:

  • Automate Shipping - Create shipments and generate labels programmatically
  • Calculate Rates - Provide accurate shipping costs to customers
  • Track Packages - Offer real-time shipment tracking
  • Validate Addresses - Ensure delivery address accuracy
  • Streamline Operations - Integrate shipping into e-commerce and fulfillment workflows

The combination of robust authentication, comprehensive service implementations, and proper error handling creates an enterprise-ready UPS integration that can scale to handle high-volume shipping operations.

Category : JAVA

Leave a Reply

Your email address will not be published. Required fields are marked *


Macro Nepal Helper