Getting started overview

Integrating with UPS APIs allows businesses to automate various logistics functions, including calculating shipping rates, generating labels, scheduling pickups, and tracking packages in real time. The process typically begins with account registration, followed by obtaining API credentials through the UPS Developer Kit. This guide details the steps to set up your environment and execute your first API call.

UPS offers a suite of APIs, primarily accessible via XML or JSON, designed for enterprise system integration. The UPS Developer Kit serves as the central resource, providing documentation, API specifications, and sample code for its various services.

API Key Components

Access to UPS APIs typically requires three primary credentials:

  • Access Key: A unique identifier for your application, granted by UPS after registration.
  • User ID: Your UPS.com username.
  • Password: Your UPS.com password.

These credentials are used together to authenticate API requests, ensuring that only authorized applications can interact with UPS services.

Create an account and get keys

To begin using UPS APIs, you must first establish a UPS business account and then enroll in the Developer Kit program to obtain your API access key. Follow these steps:

  1. Register for a UPS.com Account

    If you do not already have one, create a UPS.com account. Navigate to the official UPS account registration page and complete the signup process. This account will be linked to your API access.

  2. Sign up for the UPS Developer Kit

    Visit the UPS Developer Kit website. You will need to click on "Request an Access Key" or "Sign Up" within the developer portal. This process typically involves associating your existing UPS.com account with the developer program. During this step, you will select the specific APIs you intend to use, such as the Shipping API, Tracking API, or Rating API.

  3. Request an Access Key

    After signing up for the Developer Kit, follow the prompts to request your API Access Key. UPS typically provides this key instantly through the developer portal once your account is verified. This key is crucial for authenticating your API requests.

    Keep your Access Key, User ID, and Password secure. These credentials are required for every authenticated API request you make.

Your first request

This section will guide you through making a basic tracking API request using a sample package tracking number. The Tracking API is a common starting point due to its direct utility in monitoring package status.

API Endpoint

The base URL for UPS Tracking API requests typically points to the UPS web services environment. While specific endpoints can vary by service and environment (test vs. production), a common structure for the Tracking API might resemble https://wwwcie.ups.com/rest/Track for the test environment or https://onlinetools.ups.com/rest/Track for production. Always refer to the UPS Developer Kit documentation for the most current and precise endpoint URLs.

Request Format (Tracking API - JSON)

A JSON request for the Tracking API typically includes your credentials and the tracking number. Here's an example structure:

{
  "UPSSecurity": {
    "ServiceAccessToken": {
      "AccessLicenseNumber": "YOUR_ACCESS_KEY"
    },
    "UsernameToken": {
      "Username": "YOUR_USER_ID",
      "Password": "YOUR_PASSWORD"
    }
  },
  "TrackRequest": {
    "Request": {
      "RequestOption": "activity",
      "TransactionReference": {
        "CustomerContext": "Tracking Request from My Application"
      }
    },
    "TrackingNumber": "1Z9999999999999999" 
  }
}

Replace YOUR_ACCESS_KEY, YOUR_USER_ID, YOUR_PASSWORD, and 1Z9999999999999999 with your actual credentials and a valid UPS tracking number. You can find sample tracking numbers in the UPS Developer Kit documentation for testing purposes.

Sending the request

You can use various tools or programming languages to send this JSON payload as an HTTP POST request to the appropriate UPS Tracking API endpoint. Here's an example using curl, a common command-line tool for making web requests:

curl -X POST \
  https://wwwcie.ups.com/rest/Track \
  -H 'Content-Type: application/json' \
  -d '{
    "UPSSecurity": {
      "ServiceAccessToken": {
        "AccessLicenseNumber": "YOUR_ACCESS_KEY"
      },
      "UsernameToken": {
        "Username": "YOUR_USER_ID",
        "Password": "YOUR_PASSWORD"
      }
    },
    "TrackRequest": {
      "Request": {
        "RequestOption": "activity",
        "TransactionReference": {
          "CustomerContext": "Tracking Request from My Application"
        }
      },
      "TrackingNumber": "1Z9999999999999999" 
    }
  }'

Remember to replace the placeholder values. For production environments, ensure you use the correct production endpoint and securely manage your credentials.

Expected Response

A successful response from the Tracking API will return a JSON object containing details about the package's current status and tracking history. For instance, a basic response might look like this:

{
  "TrackResponse": {
    "Response": {
      "ResponseStatus": {
        "Code": "1",
        "Description": "Success"
      }
    },
    "Shipment": [
      {
        "ShipmentIdentificationNumber": "1Z9999999999999999",
        "Package": [
          {
            "Activity": [
              {
                "ActivityLocation": {
                  "Description": "NASHVILLE, TN, US"
                },
                "Status": {
                  "Type": "D",
                  "Description": "DELIVERED"
                },
                "Date": "20230101",
                "Time": "100000"
              }
            ]
          }
        ]
      }
    ]
  }
}

The structure and content of the response will vary based on the specific tracking number and the RequestOption specified in your request. For comprehensive details on response fields, consult the UPS Tracking API documentation.

Common next steps

After successfully making your first API call, consider these common next steps for further integration:

  1. Explore other UPS APIs

    UPS offers a range of APIs beyond tracking, including the Shipping API for label generation, the Rating API for calculating shipping costs, and the Pickup API for scheduling package pickups. Review the developer kit to identify which APIs align with your application's requirements.

  2. Implement error handling

    Integrate robust error handling mechanisms into your application to gracefully manage API failures, network issues, or invalid requests. UPS API responses include specific error codes and descriptions that can be used for debugging and user feedback. For general best practices in API error handling, refer to resources like Google Cloud's API error design guidelines.

  3. Transition to production environment

    Once your integration is thoroughly tested in the development/test environment (e.g., wwwcie.ups.com), follow UPS's guidelines to transition your application to the production environment (e.g., onlinetools.ups.com). This typically involves updating API endpoints and ensuring your Access Key is authorized for production use.

  4. Adhere to rate limits and usage policies

    Familiarize yourself with UPS's API rate limits and usage policies to avoid service interruptions. Design your application to respect these limits, potentially using caching or request queues for high-volume scenarios.

  5. Consider SDKs and libraries

    While UPS does not officially provide SDKs in various programming languages, community-driven libraries might exist to simplify integration. Searching platforms like GitHub for "UPS API client" or "UPS SDK" can reveal existing tools that abstract away some of the direct HTTP request complexities.

Troubleshooting the first call

Encountering issues during the first API call is common. Here's a quick reference table for common problems and their solutions:

Step What to do Where
Incorrect Credentials Verify Access Key, User ID, and Password accuracy. Ensure there are no typos or extra spaces. UPS Developer Kit (for Access Key), UPS.com (for User ID/Password)
Incorrect Endpoint Confirm you are using the correct API endpoint for the service (e.g., Tracking, Shipping) and environment (test vs. production). UPS API documentation specific to the service
JSON/XML Formatting Errors Check the request payload for syntax errors (e.g., missing commas, brackets, incorrect field names). Use a JSON validator if necessary. Your code editor, online JSON validator tools
Firewall/Network Issues Ensure your network allows outbound connections to UPS API servers. Proxy settings or corporate firewalls can block requests. Your network administrator, system's firewall settings
Invalid Tracking Number Verify the tracking number is valid and in the correct format. Use a known valid sample tracking number for initial tests. UPS Tracking page (to manually verify), UPS Developer Kit (for sample numbers)
Rate Limit Exceeded If you receive rate limit errors, reduce the frequency of your requests. Review UPS API usage policies

If you continue to experience issues, consult the error codes and messages returned in the API response. The UPS Developer Kit support resources can provide further assistance. Remember that API integrations require careful attention to detail for both request structure and credential management.