UPSTrackAlert-Ready.yaml

openapi: 3.1.0
info:
  title: UPS Track Alert API v2
  description: |

    # Product Info

    The UPS Track Alert API provides best in-class package tracking visibility with near real time event updates for an improved customer experience and stream line logistic management.
    Updates are pushed to the user as soon as available with no constant polling required, thereby improving operational efficiency. For more information on the UPS Track Alert API, please visit the <a href="https://developer.ups.com/api/reference/trackalertenhanced/product-info"
    target="_blank" rel="noopener">Product Info</a> page.
    
    Simplify your workflow with the API Request Generator and create your custom request body in just seconds.
    
    <a href="https://developer.ups.com/apirequestgenerator" target="_blank" rel="noopener noreferrer">
      <img src="https://www.ups.com/assets/resources/webcontent/images/APIRequestGenerator.svg" alt="API Request Generator " style="width: 150px; height: 32px;">
      
    <br/><p>Try out UPS APIs with example requests using Postman and learn more about the UPS Postman Collection by visiting our <a href="https://developer.ups.com/api/reference/postman/guide"
    target="_blank" rel="noopener">Postman Guide</a>. Explore API documentation and sample applications through GitHub.</p>

    <a href="https://god.gw.postman.com/run-collection/29542085-7513df2c-af1b-4e5c-8b5d-5797d03a6a44?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D29542085-7513df2c-af1b-4e5c-8b5d-5797d03a6a44%26entityType%3Dcollection%26workspaceId%3D7e7595f0-4829-4f9a-aee1-75c126b9d417" target="_blank" rel="noopener noreferrer">
      <img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height: 32px;"></a>
    <a href="https://github.com/UPS-API" target="_blank" rel="noopener noreferrer">
      <img src="https://www.ups.com/assets/resources/webcontent/images/gitHubButton.svg" alt="Open in GitHub" style="width: 128px; height: 32px;">
    </a>
    
    # Business Values
  
    - **Enhanced Customer Experience**: Near real-time tracking information increases transparency, leading to higher customer satisfaction and trust.
    - **Operational Efficiency**: Eliminates the necessity for continuous polling, thus saving resources and improving system responsiveness.
    - **Data-Driven Decision Making**: Access to near real-time data can help businesses optimize their supply chain and make informed logistics decisions.
    - **Optimizing Cash Flow Through Near Real-Time Delivery Tracking**: Improve cash flow by knowing that deliveries occurred in near real time.
    - **Mitigating Fraud and Theft through Near Real-Time Package Status Monitoring**: Reduce fraud and theft by knowing any time something happens to your packages.

    
    # Reference
    - <a href="https://developer.ups.com/api/reference/tracking/appendix" target="_blank" rel="noopener">Appendix</a>
    - <a href="https://developer.ups.com/api/reference/trackalert/faq" target="_blank" rel="noopener">FAQ</a>
    - <a href="https://developer.ups.com/api/reference/trackalert/V1VsV2" target="_blank" rel="noopener">Track Alert v1 vs v2</a>
    
    # Overview
      When the UPS system is unable to respond to a request, be it from a malformed request, an illegal or invalid value, or other issues, the API generates an error response.
      
      Successful responses may or may not include warnings.
      1. **Without warnings** - Indicates the request has been processed as anticipated.
      2. **With warnings** - Indicates the request has been processed with potentially unanticipated results. The warning contains information in the response that should be passed to the end user.
      
      The severity of an error may be transient or hard.
      1. **Transient error** - Indicates an error that is temporary in nature. Such errors may be caused by response timeouts due to high server loads or scheduled maintenance in progress. The request may be issued successfully at a later time.
      2. **Hard error** - Indicates the request has a problem that the system is not able to resolve. These errors are critical and prevent requests from processing.
      
      The following error codes can apply to all APIs. 
      
    # Error Codes

    | **Code**  | **HTTP Code** | **Severity**  | **Description**                                                                                                                                                                                       |
    | :--:      | :---:         | :---:         | :--                                                                                                                                                                                                   |
    | UJ0001    | 401           | Hard          | Invalid token or token is not present                                                                                                                                                                    |
    | 405       | 405           | Hard          | Method Not Allowed.                                                                                                                                                                                   |
    | 10004     | 500           | Transient     | Something went wrong while processing your request, please try again later                                                                                                                            |
    | 10007     | 400           | Hard          | Requested Content Type is not supported                                                                                                                                                               |
    | 250002    | 401           | Hard          | Invalid authentication information.                                                                                                                                                |
    | 251004    | 401           | Hard          | Bearer Token expired (oauth)                                                                                                                                                                          |
    | VSS000    | 400           | Hard          | Invalid request and The Subscription request has been rejected.                                                                                                                                       |
    | VSS002    | 400           | Hard          | Missing transId                                                                                                                                                                                       |
    | VSS003    | 400           | Hard          | Please enter a valid Transaction ID, The Subscription request has been rejected.                                                                                                                      |
    | VSS004    | 400           | Hard          | Missing transactionSrc                                                                                                                                                                       |
    | VSS006    | 400           | Hard          | Please enter a valid Transaction SRC, The Subscription request has been rejected.                                                                                                                                 |
    | VSS100    | 500           | Transient     | We're sorry, the system is temporarily unavailable.  Please try again later.                                                                                                                          |
    | VSS110    | 400           | Hard          | Subscription request is empty or not present. The Subscription request has been rejected.                                                                                                             |
    | VSS200    | 400           | Hard          | Tracking Number List is required. The Subscription request has been rejected.                                                                                                                         |
    | VSS210    | 400           | Hard          | The Subscription request should have at least one valid tracking number. The Subscription request has been rejected.                                                                                  |
    | VSS215    | 400           | Hard          | The tracking number that was submitted is not a valid CIE tracking number and has been rejected.                                                                                                                |
    | VSS220    | 400           | Hard          | You have submitted over 100 tracking numbers which is not allowed. The entire submission of tracking numbers has been rejected.  Please resubmit your request again using groups of no more than 100 tracking numbers.  |
    | VSS300    | 400           | Hard          | Locale is required. The Subscription request has been rejected.                                                                                                                                       |
    | VSS310    | 400           | Hard          | Please enter a valid locale. The Subscription request has been rejected                                                                                                                               |
    | VSS400    | 400           | Hard          | Please enter a valid country code. The Subscription request has been rejected.                                                                                                               |
    | VSS500    | 400           | Hard          | Destination is required. The Subscription request has been rejected                                                                                                                                   |
    | VSS600    | 400           | Hard          | URL is empty or not present. The Subscription request has been rejected.                                                                                                                              |
    | VSS610    | 400           | Hard          | URL is too long. The Subscription request has been rejected.                                                                                                                                          |
    | VSS700    | 400           | Hard          | Credential is empty or not present. The Subscription request has been rejected.                                                                                                                       |
    | VSS800    | 400           | Hard          | CredentialType is empty or not present. The Subscription request has been rejected.                                                                                                                                        |
    | VSS930    | 400           | Hard          | Type is missing or invalid, The Subscription request has been rejected.                                                                                                                               |


servers:
  - url: https://wwwcie.ups.com/api/track/{version}
    description: Customer Integration Environment

  - url: https://onlinetools.ups.com/api/track/{version}
    description: Production

security: 
  - oauth2: [] 
tags:
  - name: UPS Track Alert
    description: Endpoints related to tracking subscriptions
paths:
  /subscription/{type}/package:
    post:
      description: |
        This endpoint takes a list of tracking numbers and creates a subscription for each.
        Clients must provide the tracking numbers in the correct format.
        
        **Note:** The current version of the Track Alert API is v2. While v1 remains supported, we recommend using v2 for all new integrations and future development. In v2, the destination object has been removed, and webhook credentials are now managed through [Manage Webhook Credentials](https://developer.ups.com/update-webhook).
        
        Upon success it should return:
        - List of valid tracking number for which subscription created.
        - List of invalid tracking number for which subscription not created.
       
      tags:
        - UPS Track Alert
      summary: API to create subscriptions by tracking numbers.
      operationId: processSubscriptionTypeForTrackingNumber
      security:
        - oauth2: []
      parameters:
        - in: path
          name: version
          required: true
          schema:
            type: string
            default: v2
            enum:
              - v2
          description: |
            Version

            Valid values:
            - v2
        - $ref: "#/components/parameters/transId"
        - $ref: "#/components/parameters/transactionSrc"
        - $ref: "#/components/parameters/type"
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PackageSubscriptionRequest'
            examples:
              'Standard Request':
                summary: Standard Request
                value:
                  locale: en_US
                  countryCode: US
                  trackingNumberList:
                    - 1ZCIETST0111111114
                    - 1ZCIETST0422222228
              'Enhanced Request':
                summary: Enhanced Request
                value:
                  locale: en_US
                  countryCode: US
                  trackingNumberList:
                    - 1ZCIETST0111111114
                    - 1ZCIETST0422222228
                  eventPreferences:
                    - D
                    - I
                    - M
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageSubscriptionSuccessResponse'
              examples:
                PartialSuccessExample:
                  description: Example response that contains valid tracking number for which subscription created and invalid tracking numbers.
                  value:
                    validTrackingNumbers:
                      - 1Z1234567891234556
                    invalidTrackingNumbers:
                      - 1Z1234567$8
                CompleteSuccessExample:
                  description: Example response that contains valid tracking numbers for which subscription created.
                  value:
                    validTrackingNumbers:
                      - 1Z1234567891234556
        '400':
          description: Invalid Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageSubscriptionErrorResponse'
              example:
                invalidTrackingNumbers: 
                  - 1Z1234567$8
                response:
                  errors:
                    - code: VSS300
                      message: Locale is required. The Subscription request has been rejected.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                response:
                  errors:
                    - code: "250002"
                      message: Invalid Authentication Information
        '404':
          description: URL does not exist or resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                response:
                  errors:
                    - code: "404"
                      message: The requested resource was not found.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
              example:
                response:
                  errors:
                    - code: "10004"
                      message: Something went wrong while processing your request, please try again later
  webhooks:
  TrackingEvent:
    post:
      summary: Tracking Event
      description: This HTTPS POST request will send information about a new tracking event in the system. Please ensure the webhook URL provided in the subscription request is ready to receive this POST request. Note that not every field will have a value in each message.
      operationId: trackingEvent
      tags:
        - UPS Track Alert
      security:
        - clientOauth2: [ ]
      parameters:
        - name: x-api-key
          in: header
          description: It is a string filed in header, which holds the clientID of the OAUTH token used for authentication. This is required for OAUTH clients and optional for non-OAUTH clients.
          required: false
          schema:
            type: string
        - name: User-Agent
          in: header
          description: Represents Track Alert application with value 'UPSPubSubTrackingService'.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrackingEventRequest'
            examples:
              'Out for delivery message':
                summary: Out for delivery message
                value:
                  trackingNumber: 1Z204W4R0308071865
                  localActivityDate: '20240423'
                  localActivityTime: '091519'
                  activityLocation:
                    city: Charlotte
                    stateProvince: NC
                    postalCode: '30004'
                    country: US
                  activityStatus:
                    type: I
                    code: OT
                    description: Out for Delivery
                    descriptionCode: 021
                  scheduledDeliveryDate: '20240423'
                  gmtActivityDate: '20240423'
                  gmtActivityTime: '131519'
                  deliveryTimeDescription: end of day
              '2':
                summary: Delivery message
                value:
                  trackingNumber: 1Z204W4R0308071865
                  localActivityDate: '20240423'
                  localActivityTime: '095004'
                  activityLocation:
                    city: CHARLOTTE
                    stateProvince: NC
                    postalCode: '28209'
                    country: US
                  activityStatus:
                    type: D
                    code: FS
                    description: Delivered
                    descriptionCode: 011
                  scheduledDeliveryDate: '20191014'
                  gmtActivityDate: '20240423'
                  gmtActivityTime: '135004'
                  actualDeliveryDate: '20240423'
                  actualDeliveryTime: '095004'
                  receivedBy: 'John'
      responses:
        '200':
          description: Return a 200 status to indicate that the data was received successfully
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: |
        Find your Client ID and Secret on your app info page. 
          1. Select "Try It" 
          2. In the Security section enter your Client ID and Secret 
          3. Select "Request Token"
          4. Enter any additional information in the Body and Parameters sections
          5. Select "Send" to execute your API request"
      flows:
        clientCredentials:
          x-tokenEndpointAuthMethod: client_secret_basic
          tokenUrl: https://onlinetools.ups.com/security/v1/oauth/token
          scopes: {}
    clientOauth2:
      type: oauth2
      description: |
        Oauth Token generator provide by the customer.
      flows:
        clientCredentials:
          x-tokenEndpointAuthMethod: client_secret_basic
          tokenUrl: https://your-token-url.com/oauth/token
          scopes: { }
  parameters:
    shipper-account-number:
      name: shipper_account_number
      in: query
      required: true
      schema:
        $ref: '#/components/schemas/AccountNumber'
    transId:
      name: transId
      in: header
      description: An identifier unique to the request.
      required: true
      schema:
        type: string
    transactionSrc:
      name: transactionSrc
      in: header
      description: Identifies the client/source application that is calling.
      required: true
      schema:
        type: string
    type:
      name: type
      in: path
      required: true
      description: Represents a subscription type that provides near real time updates on tracking status.
      schema:
        type: string
        description: type of subscription being requested
        oneOf:
          - title: standard
            description: Returns standard event data to the webhook.
            const: standard
          - title: enhanced
            description: Adds additional webhook details as requested through the request 'eventPreferences' code. Currently available for package subscription request only.
            const: enhanced
  schemas:
    #ACCOUNT
    AccountSubscriptionRequest:
      allOf:
        - $ref: '#/components/schemas/CommonRequest'
        - type: object
          required:
            - shipperAccountNumber
          properties:
            subscriptionId:
              type: string
              description: Required for non-XOLT clients.
              example: UPS_Client
            clientSubscriptionId:
              type: string
              description: Required for non-XOLT clients.
              example: UPS_Client
            shipperAccountNumber:
              $ref: '#/components/schemas/AccountNumber'
            subAccountType:
              type: array
              description: Unbounded array of the packages account types
              uniqueItems: true
              items:
                type: string
                description: The account type used for package event identification.
                enum: 
                  - Outbound
          additionalProperties: true
    AccountSubscriptionResponse:
      type: object
      properties:
        expiryDate:
          type: string
          format: date
          example: 9999-12-31
          description: Represents date of expiry for the subscription.
      additionalProperties: false
    AccountUnsubscribeResponse:
      type: object
      properties:
        message:
          type: string
          example: "Account unsubscribed"
          description: Represents message for the un-subscription.
      additionalProperties: false

    #PACKAGE
    PackageSubscriptionRequest:
      allOf:
        - $ref: '#/components/schemas/CommonRequest'
        - type: object
          required:
            - trackingNumberList
          properties:
            trackingNumberList:
              type: array
              description: Represents list of tracking numbers in request.
              maxItems: 100
              examples: 
                - 1Z1234567891234556
                - 1R12345678912345
              items:
                $ref: '#/components/schemas/TrackingNumber'
          additionalProperties: true
    PackageSubscriptionSuccessResponse:
      type: object
      description: container for package subscription response details
      properties:
        validTrackingNumbers:
          type: array
          description: Unbounded list of tracking numbers with successful subscription created.
          items:
            $ref: '#/components/schemas/TrackingNumber'
          examples: 
            - 1Z1234567891234556
            - 1R12345678912345
        invalidTrackingNumbers:
          type: array
          description: List of tracking numbers associated with errors preventing subscription creation.
          items:
            type: string
          example: 
            - 1Z1234567$8
      additionalProperties: false
    PackageSubscriptionErrorResponse:
      allOf:
        - type: object
          properties:        
            invalidTrackingNumbers:
              $ref: "#/components/schemas/PackageSubscriptionSuccessResponse/properties/invalidTrackingNumbers"
          additionalProperties: true
          required:
            - invalidTrackingNumbers
        - $ref: '#/components/schemas/ErrorMessage'

    #WEBHOOK
    TrackingEventRequest:
      required:
        - trackingNumber
        - activityStatus
      type: object
      description: Package event update payload.
      properties:
        trackingNumber:
           $ref: '#/components/schemas/TrackingNumber'
        localActivityDate:
          description: 'The localized date of the activity. Format: YYYYMMDD'
          $ref: '#/components/schemas/Date'
        localActivityTime:
          description: 'The localized time of the activity. Format: HHMMSS (24 hr)'
          $ref: '#/components/schemas/Time'
        activityLocation:
          type: object
          description: The container which has the current package activity location.
          properties:
            city:
              type: string
              description: The physical address city.
              example: Alpharetta
            stateProvince:
              type: string
              description: The physical address state or province.
              minLength: 2
              maxLength: 2
              pattern: ^[A-Z]{2}$
              example: GA
            postalCode:
              type: string
              description: The physical address postal code (This field is blank until the delivery event occurs).
              minLength: 5
              maxLength: 9
              pattern: ^\d{5}(?:[-\s]\d{4})?$
              examples:
                - "30004"
                - "30004-4616"
            country:
              $ref: '#/components/schemas/Country'
        activityStatus:
          type: object
          description: The container which has the current package activity status.
          properties:
            type:
              type: string
              description: |
                The current activity status type.
              oneOf:
                - const: D
                  title: Delivery
                - const: I
                  title: On the Way
                - const: M
                  title: Manifest
                - const: MV
                  title: Manifest Void
                - const: U
                  title: Updated Delivery Date or Time
                - const: X
                  title: Package Exception
            code:
              type: string
              description: |
                The current activity status code. See the 'Status Codes' document for more details.
            description:
              type: string
              description: | 
                The current activity status description.
        scheduledDeliveryDate:
          description: 'Original scheduled delivery date of the package. Format: YYYYMMDD'
          $ref: '#/components/schemas/Date'
        actualDeliveryDate:
          description: 'Actual delivery date of the package. Format: YYYYMMDD (This field is blank until the delivery event occurs)'
          $ref: '#/components/schemas/Date'
        actualDeliveryTime:
          description: 'Actual delivery time of the package. Format: HHMMSS (24 hr) (This field is blank until the delivery event occurs)'
          $ref: '#/components/schemas/Time'
        gmtActivityDate:
          description: 'The GMT date of the activity. Format: YYYYMMDD'
          $ref: '#/components/schemas/Date'
        gmtActivityTime:
          description: 'The GMT time of the activity. Format: HHMMSS (24 hr)'
          $ref: '#/components/schemas/Time'
        gmtOffset:
          type: string
          description: "A field that shows how local time was calculated. In the format (-/+)HH.MM (24 hr)"
          minLength: 6
          maxLength: 6
          pattern: ^[+-]([01]\d|2[0-3])\.[0-5]\d$
          example: "-04.00"
        deliveryStartTime:
          description: 'The start time of a delivery. Format: HHMMSS (24 hr).'
          $ref: '#/components/schemas/Time'
        deliveryEndTime:
          description: 'The end time of a window or the committed time or the delivered time. Format: HHMMSS (24 hr)'
          $ref: '#/components/schemas/Time'
        deliveryTimeDescription:
          type: string
          description: The date of this delivery detail.
        deliveryPhoto:
          type: string
          description: |
            Base64 encoded image of the delivery photo (This field is blank until the delivery photo is made available for enhanced subscriptions).
        alternateTrackingNumber:
          type: string
          description: |
            Alternate tracking number for the package.
          pattern: (^1Z[0-9A-Z]{16}$)|(^1R[0-9A-Z]{14}$)|(^1R[0-9A-Z]{26}$)
          examples:
            - 1Z1234567891234551
        receivedBy:
          type: string
          description: Clarified signature provided with delivery, when available. (This field is only available for enhanced users)

    #COMMON
    AccountNumber:
      type: string
      description: The shipper account number for which subscription is requested.
      example: "123456"
    CommonRequest:
      type: object
      description: Common properties for both account and package subscription requests
      properties:
        locale:
          $ref: '#/components/schemas/Locale'
        countryCode:
          $ref: '#/components/schemas/Country'
        eventPreferences:
          $ref: '#/components/schemas/EventPreferences'
      required: 
        - locale
      additionalProperties: true
    Country:
      type: string
      description: The physical address <a href="https://www.iso.org/iso-3166-country-codes.html" target="_blank">ISO 3166</a> country or territory code
      minLength: 2
      maxLength: 2
      pattern: ^[A-Z]{2}
      example: US
    Date:
      type: string      
      minLength: 8
      maxLength: 8
      pattern: ^\d{4}(0[1-9]|1[012])(0[1-9]|[12][0-9]|3[01])$
      example: "20191014"
    EventPreferences:
      type: array
      description: |
        Represents scan/event preferences for the subscription endpoint. If no value is provided in this array
        then all activity types will be sent. (This field is only for enhanced users)
      minItems: 1
      maxItems: 4
      items:
        type: string
        description: package activity identifier
        oneOf:
          - const: D
            title: Delivery
            description: Includes updates and delivery photo
          - const: I
            title: In-Progress
          - const: M
            title: Manifest
          - const: X
            title: Exception
            description: Includes updates
    Locale:
      type: string
      description: >
        Locale setting is composed of ISO 639 language code and ISO 3166 country code,
        separated by an underscore.
        Currently only English (en_US) is supported, but this field is extensible for future locales.
      pattern: ^[a-z]{2}_[A-Z]{2}$
      example: en_US
    Time:
      type: string      
      minLength: 6
      maxLength: 6
      pattern: ^([01]?\d|2[0-3])([0-5]?\d){2}$
      example: "235959"
    TrackingNumber:
      type: string
      description: Represents tracking numbers starting with '1Z' followed by 16 alphanumeric characters, or '1R' followed by 14 or 26 alphanumeric characters, in request.
      pattern: (^1Z[0-9A-Z]{16}$)|(^1R[0-9A-Z]{14}$)|(^1R[0-9A-Z]{26}$)
      examples:
        - 1Z1234567891234556
        - 1R12345678912345
        - 1R123456789123456789012345
    ErrorMessage:
      type: object
      description: Response object for errors
      properties:
        response:
          description: Response container to store errors
          type: object
          properties: 
            errors:
              type: array
              description: Unbounded array containing one or more error objects
              items: 
                type: object
                description: Error entity
                properties: 
                  code:
                    type: string
                    description: error code
                    minLength: 1
                    example: VSS300
                  message:
                    type: string
                    description: error message
                    minLength: 1
                    example: Locale is required. The Subscription request has been rejected.
                required: 
                  -  code
                  -  message
                additionalProperties: false
          required: 
            -  errors
          additionalProperties: false
      required: 
        - response
      additionalProperties: true