Try out UPS APIs with example requests using Postman and learn more about the UPS Postman Collection by visiting our Postman Guide. Explore API documentation and sample applications through GitHub.
servers:
- url: https://wwwcie.ups.com/api
description: Customer Integration Environment
- url: https://onlinetools.ups.com/api
description: Production
paths:
"/shipments/{version}/transittimes":
post:
summary: TimeInTransit
tags:
- Time in Transit
security:
- OAuth2: []
operationId: TimeInTransit
parameters:
- in: path
name: version
schema:
type: string
default: v1
description: API Version
required: true
- in: header
name: transId
schema:
type: string
description: An identifier unique to the request. Length 32
required: true
- in: header
name: transactionSrc
schema:
type: string
default: testing
description: Identifies the clients/source application that is calling. Length
512
required: true
requestBody:
description: Generate sample code for popular API requests by selecting an
example below. To view a full sample request and response, first click "Authorize"
and enter your application credentials, then populate the required parameters
above and click "Try it out".
required: true
content:
application/json:
schema:
"$ref": "#/components/schemas/TimeInTransitRequest"
examples:
'1':
summary: A sample JSON request (Standard Example)
value:
originCountryCode: DE
originStateProvince: ''
originCityName: ''
originTownName: ''
originPostalCode: '10703'
destinationCountryCode: US
destinationStateProvince: NH
destinationCityName: MANCHESTER
destinationTownName: ''
destinationPostalCode: '03104'
weight: '10.5'
weightUnitOfMeasure: LBS
shipmentContentsValue: '10.5'
shipmentContentsCurrencyCode: USD
billType: '03'
shipDate: '2019-05-01'
shipTime: ''
residentialIndicator: ''
avvFlag: true
numberOfPackages: '1'
responses:
'200':
description: successful operation
content:
application/json:
schema:
"$ref": "#/components/schemas/TimeInTransitResponse"
'400':
description: Invalid Request
content:
application/json:
schema:
"$ref": "#/components/schemas/errorResponse"
'401':
description: Unauthorized Request
content:
application/json:
schema:
"$ref": "#/components/schemas/errorResponse"
'403':
description: Blocked Merchant
content:
application/json:
schema:
"$ref": "#/components/schemas/errorResponse"
'429':
description: Rate Limit Exceeded
content:
application/json:
schema:
"$ref": "#/components/schemas/errorResponse"
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://wwwcie.ups.com/security/v1/oauth/token
scopes: {}
schemas:
TimeInTransitRequest:
type: object
required:
- originCountryCode
properties:
originCountryCode:
description: "The country code of the origin shipment. \nValid Values: \nMust
conform to the ISO-defined, two-letter country or territory codes. Refer
to Country or Territory Codes in the Appendix above for valid values."
type: string
maximum: 1
minLength: 2
maxLength: 2
originStateProvince:
description: "The shipment origin state or province. For U.S. addresses,
the value must be a valid 2-character value (per U.S. Mail standards)
\n For non-U.S. addresses the full State or Province name should be provided."
type: string
maximum: 1
minLength: 1
maxLength: 50
originCityName:
description: The shipment origin city. Required for International requests
for those countries that do not utilize postal codes.
type: string
maximum: 1
minLength: 1
maxLength: 50
originTownName:
description: The shipment origin town. Town is a subdivision of city.
type: string
maximum: 1
minLength: 1
maxLength: 50
originPostalCode:
description: "Required for Domestic requests. The shipment origin postal
code. \nEither the 5, or 9-digit US zip codes must be used for U.S. addresses.
\ For non-U.S. addresses, this is recommended for all countries that utilize
postal codes."
type: string
maximum: 1
minLength: 1
maxLength: 10
destinationCountryCode:
description: "The country code of the destination. \n Valid values: \n
Must conform to ISO-defined country codes."
type: string
maximum: 1
minLength: 2
maxLength: 2
destinationStateProvince:
description: "The shipment destination state or province. For U.S. addresses,
the value must be a valid 2-character value (per U.S. Mail standards).
\ \n For non-U.S. addresses the full State or Province name should be
provided."
type: string
maximum: 1
minLength: 1
maxLength: 50
destinationCityName:
description: The shipment destination city. Required for International Requests
for those countries that do not utilize postal codes.
type: string
maximum: 1
minLength: 1
maxLength: 50
destinationTownName:
description: The shipment destination town. Town is a subdivision of city.
type: string
maximum: 1
minLength: 1
maxLength: 50
destinationPostalCode:
description: "The shipment destination postal code. \n Required for Domestic
requests. Either 5, or 9-digit U.S. zip codes must be used for U.S. addresses.
\ For non-U.S. addresses, this is recommended for all countries that utilize
postal codes."
type: string
maximum: 1
minLength: 1
maxLength: 10
residentialIndicator:
description: "Indicates if address is residential or commercial. Required
for Domestic requests. \n \n Valid values: \"01\", \"02\" \n \n 01 = Residential
\n 02 = Commercial \n \n Defaults to commercial for International Requests."
type: string
maximum: 1
minLength: 2
maxLength: 2
shipDate:
description: "The date the shipment is tendered to UPS for shipping (can
be dropped off at UPS or picked up by UPS). Allowed range is up to 60
days in future and 35 days in past. This date may or may not be the UPS
business date. \n\nFormat is YYYY-MM-DD. \n\nYYYY = 4 digit year; \n\nMM
= 2 digit month, valid values 01-12; \n\nDD = 2 digit day of month, valid
values 01-31 \n If no value is provided, defaults to current system date."
type: string
maximum: 1
minLength: 1
maxLength: 10
shipTime:
description: "The time the shipment is tendered to UPS for shipping (can
be dropped off at UPS or picked up by UPS). \n Format is HH:MM:SS \n\n
Defaults to current time if not provided."
type: string
maximum: 1
minLength: 1
maxLength: 8
weight:
description: "The weight of the shipment. Required for International requests.
\n \n Note: If decimal values are used, valid values will be rounded to
the tenths. \n \n Note: Maximum value is 70 kilograms or 150 pounds."
type: number
maximum: 1
minLength: 1
maxLength: 8
weightUnitOfMeasure:
description: "Required for International requests and when weight value
is provided. \n \n Valid Values: \"LBS\", \"KGS\""
type: string
maximum: 1
minLength: 1
maxLength: 3
shipmentContentsValue:
description: "The monetary value of shipment contents. \n \n Required when
origin country does not equal destination country and BillType is 03 (non-documented)
or 04 (WWEF) \n \n Required when origin country does not equal destination
country, and destination country = CA, and BillType = 02 (document). \n
\n Note: If decimal values are used, valid values will be rounded to the
tenths."
type: number
maximum: 3
minLength: 1
maxLength: 11
shipmentContentsCurrencyCode:
description: "The unit of currency used for values. Required if ShipmentContentsValue
is populated. \n Valid value: must conform to ISO standards."
type: string
maximum: 1
minLength: 1
maxLength: 3
billType:
description: "Required for International Requests. \n Valid values: \"02\",\"03\",\"04\"
\n 02 - Document \n 03 - Non Document \n 04 - WWEF (Pallet)"
type: string
maximum: 1
minLength: 2
maxLength: 2
avvFlag:
description: "Used to bypass address validation when the address has already
been validated by the calling application. \n \n Valid values: true,
false \n \n Defaults to true \n Note: not to be exposed to external customers."
type: boolean
maximum: 1
numberOfPackages:
description: Sets the number of packages in shipment. Default value is
1.
type: integer
maximum: 1
dropOffAtFacilityIndicator:
description: "Sets the indicator for an international Freight Pallet shipment
that is going to be dropped off by shipper to a UPS facility. The indicator
is used when the Bill Type is \"04\". \n \n Valid values: \"0\", \"1\".
\n \n 0 = WWDTProcessIF.PICKUP_BY_UPS \n 1 = WWDTProcessIf.DROPOFF_BY_SHIPPER
\n \n The default value is \"0\" "
type: integer
maximum: 1
holdForPickupIndicator:
description: "Sets the indicator for an international Freight Pallet shipment
that is going to be pick-up by consignee in a destination facility. The
indicator is used when the Bill Type is \"04\". \n \n Valid values: \"0\",
\"1\". \n \n 0 = WWDTProcessIF.DELIVERY_BY_UPS \n 1 = WWDTProcessIf.PICKUP_BY_CONSIGNEE
\n \n The default value is \"0\" "
type: integer
maximum: 1
returnUnfilterdServices:
description: "Used to get back a full list of services - bypassing current
WWDT business rules to remove services from the list being returned to
clients for US domestic that are slower than UPS Ground. \n \n Default
value is false."
type: boolean
maximum: 1
maxList:
description: "Sets the limit for the number of candidates returned in candidate
list. \n \n Default value is 200."
type: integer
maximum: 1
premierIndicator:
description: "Sets the indicator for premier time in transit when the shipment contains a premier package.
\n \n Valid values: “00”, “01”. \n \n 00 = Non-premier time in transit.
\n \n 01 = Premier time in transit. \n \n The default value is “00”."
type: string
maximum: 1
minLength: 2
maxLength: 2
maximum: 1
description: N/A
TimeInTransitResponse:
type: object
properties:
validationList:
"$ref": "#/components/schemas/validationList"
destinationPickList:
"$ref": "#/components/schemas/destinationPickList"
originPickList:
"$ref": "#/components/schemas/originPickList"
emsResponse:
"$ref": "#/components/schemas/emsResponse"
maximum: 1
description: N/A
errorResponse:
type: object
properties:
errors:
type: array
items:
"$ref": "#/components/schemas/errors"
validationList:
type: object
properties:
invalidFieldList:
type: array
items:
type: string
invalidFieldListCodes:
type: array
items:
type: string
destinationAmbiguous:
description: Returned as true when destination address has a candidate list
type: boolean
maximum: 1
originAmbiguous:
description: Returned as true when original address has a candidate list.
type: boolean
maximum: 1
destinationPickList:
type: array
items:
"$ref": "#/components/schemas/candidateAddress"
originPickList:
type: array
items:
"$ref": "#/components/schemas/candidateAddress"
emsResponse:
type: object
required:
- shipDate
- shipTime
- serviceLevel
- billType
- residentialIndicator
- destinationCountryName
- destinationCountryCode
- originCountryName
- originCountryCode
- guaranteeSuspended
- numberOfServices
properties:
shipDate:
description: "The date the shipment is tendered to UPS for shipping (can
be dropped off at UPS or picked up by UPS). This date may or may not
be the UPS business date. \n \n Valid Format: YYYY-MM-DD"
type: string
maximum: 1
minLength: 8
maxLength: 8
shipTime:
description: "The time the shipment is tendered to UPS for shipping (can
be dropped off at UPS or picked up by UPS). \n \n Valid Format: HH:MM:SS"
type: string
maximum: 1
serviceLevel:
description: "Service Levels being returned. \n \n A = all service levels.
\n \n Blank is the default for all Service Level values."
type: string
maximum: 1
minLength: 1
maxLength: 3
billType:
description: "Represents the shipment type. \n \n Valid values: \"02\",\"03\",\"04\",\"07\"
\n 02 - Document \n 03 - Non-Document \n 04 - WWEF \n 07 - Pallet"
type: string
maximum: 1
minLength: 2
maxLength: 2
dutyType:
description: "Populated with valid duty types for international transactions
only. \n \n Valid Duty Types: \"01\",\"02\",\"03\",\"04\",\"05\",\"06\",\"07\",\"08\",\"09\"
\n 01 - Dutiable \n 02 - Non Dutiable \n 03 - Low Value \n 04 - Courier
Remission \n 05 - Gift \n 06 - Military \n 07 - Exception \n 08 - Line
Release \n 09 - Low Value"
type: string
maximum: 1
minLength: 2
maxLength: 2
residentialIndicator:
description: "residential Indicator that was sent in on the request. \n
\n Valid values: \"01\",\"02\" \n \n 01 - Residential \n 02 - Commercial"
type: string
maximum: 1
minLength: 2
maxLength: 2
destinationCountryName:
description: Destination country name value
type: string
maximum: 1
minLength: 1
maxLength: 50
destinationCountryCode:
description: Destination country code, conforms to ISO-defined country codes.
type: string
maximum: 1
minLength: 2
maxLength: 2
destinationPostalCode:
description: "The shipment destination postal code. Required for US domestic
requests. \n \n Either 5, or 9-digit US zip codes must be used for U.S.
addresses. For non-US addresses, this is recommended for all countries
that utilize postal codes."
type: string
maximum: 1
minLength: 1
maxLength: 10
destinationPostalCodeLow:
description: "The shipment destination postal code low range. Value may
or may not differ from destinationPostalCode. \n \n Either 5, or 9-digit
US zip codes must be used for U.S. addresses. For non-US addresses, this
is recommended for all countries that utilize postal codes."
type: string
maximum: 1
minLength: 1
maxLength: 10
destinationPostalCodeHigh:
description: "The shipment destination postal code high range. Value may
or may not differ from destinationPostalCode. \n \n Either 5, or 9-digit
US zip codes must be used for U.S. addresses. For non-US addresses, this
is recommended for all countries that utilize postal codes."
type: string
maximum: 1
minLength: 1
maxLength: 10
destinationStateProvince:
description: "The shipment destination state or province. \n \n For U.S.
addresses, the value will be a valid 2-Character value (per U.S. Mail
Standards). \n \n For non-U.S. addresses the full State or Province name
will be returned."
type: string
maximum: 1
minLength: 1
maxLength: 50
destinationCityName:
description: "The shipment destination city. \n \n Required for International
requests for those countries that do not utilize postal codes."
type: string
maximum: 1
minLength: 1
maxLength: 50
originCountryName:
description: Origin country name value
type: string
maximum: 1
minLength: 1
maxLength: 50
originCountryCode:
description: Origin country code, conforms to ISO-defined country codes.
type: string
maximum: 1
minLength: 2
maxLength: 2
originPostalCode:
description: "The shipment origin postal code. Required for US domestic
requests. \n \n Either 5, or 9-digit US zip codes must be used for U.S.
addresses. For non-US addresses, this is recommended for all countries
that utilize postal codes."
type: string
maximum: 1
minLength: 1
maxLength: 10
originPostalCodeLow:
description: "The shipment origin postal code low range. Value may or may
not differ from destinationPostalCode. \n \n Either 5, or 9-digit US
zip codes must be used for U.S. addresses. For non-US addresses, this
is recommended for all countries that utilize postal codes."
type: string
maximum: 1
minLength: 1
maxLength: 10
originPostalCodeHigh:
description: "The shipment origin postal code high range. Value may or
may not differ from destinationPostalCode. \n \n Either 5, or 9-digit
US zip codes must be used for U.S. addresses. For non-US addresses, this
is recommended for all countries that utilize postal codes."
type: string
maximum: 1
minLength: 1
maxLength: 10
originStateProvince:
description: "The shipment origin state or province. \n \n For U.S. addresses,
the value will be a valid 2-Character value (per U.S. Mail Standards).
\n \n For non-U.S. addresses the full State or Province name will be returned."
type: string
maximum: 1
minLength: 1
maxLength: 50
originCityName:
description: "The shipment origin city. \n \n Required for International
requests for those countries that do not utilize postal codes."
type: string
maximum: 1
minLength: 1
maxLength: 50
weight:
description: "Shipment weight. Value is only required for international
shipment. \n \n Defaults to 0.0"
type: string
maximum: 1
minLength: 1
maxLength: 8
weightUnitOfMeasure:
description: Returned on response when weight was present on the request.
type: string
maximum: 1
minLength: 1
maxLength: 3
shipmentContentsValue:
description: "Shipment contents value. Value is only required for international
shipment. \n \n Defaults to 0.0"
type: string
maximum: 1
minLength: 1
maxLength: 11
shipmentContentsCurrencyCode:
description: Returned on response when shipmentContentsValue was present
on the request.
type: string
maximum: 1
minLength: 3
maxLength: 3
guaranteeSuspended:
description: "Returns TRUE if the shipment dates fall within a defined peak
date range. When the guarantee is suspended, it is suspended for all services
in the response. \n \n The logic for determining if guarantees are suspended
applies per origin country. \n \n The following will be used to determine
if a shipment falls within a defined peak date range: shipDate (from the
response), deliveryDate (from the response), server Date. \n \n Defined
peak date range (range for when guarantees are suspended) is inclusive
of start and end dates."
type: boolean
maximum: 1
numberOfServices:
description: Number of services being returned in the services array.
type: integer
maximum: 1
services:
type: array
items:
"$ref": "#/components/schemas/services"
candidateAddress:
type: object
required:
- countryName
- CountryCode
properties:
countryName:
description: Spelled out country name.
type: string
maximum: 1
minLength: 1
maxLength: 50
countryCode:
description: Country code, follows ISO-defined country codes.
type: string
maximum: 1
minLength: 2
maxLength: 2
stateProvince:
description: Present on response when candidate value has a political division
1 value available.
type: string
maximum: 1
minLength: 1
maxLength: 50
city:
description: Present on response when candidate value has a political division
2 value available.
type: string
maximum: 1
minLength: 1
maxLength: 50
town:
description: Present on response when candidate value has a political division
3 value available.
type: string
maximum: 1
minLength: 1
maxLength: 50
postalCode:
description: Present on response when candidate has a postal code value
available
type: string
maximum: 1
minLength: 1
maxLength: 10
postalCodeLow:
description: Present on response when candidate value has a postal code
range value available. This is the postal range low value.
type: string
maximum: 1
minLength: 1
maxLength: 10
postalCodeHigh:
description: Present on response when candidate value has a postal code
range value available. This is the postal range high value.
type: string
maximum: 1
minLength: 1
maxLength: 10
services:
type: object
required:
- serviceLevel
- serviceLevelDescription
- shipDate
- deliveryDate
- commitTime
- deliveryTime
- deliveryDayOfWeek
- nextDayPickupIndicator
- saturdayPickupIndicator
- saturdayDeliveryIndicator
- guaranteeIndicator
- totalTransitDays
- businessTransitDays
- restDaysCount
- holidayCount
- delayCount
- pickupDate
- pickupTime
- cstccutoffTime
properties:
serviceLevel:
description: "Service level code \n \n Valid domestic service codes: \"1DMS\",\"1DAS\",\"1DM\",\"1DA\",\"1DP\",\"2DM\",\"2DA\",\"3DS\",\"GND\".
\n \n Valid International service codes (not a complete list) ,\"01\",\"02\",\"03\",\"05\",\"08\",\"09\",\"10\",\"11\",\"18\",\"19\",\"20\",\"21\",\"22\",\"23\",\"24\",\"25\",\"26\",\"28\",\"29\",\"33\",\"68\". "
type: string
maximum: 1
minLength: 2
maxLength: 2
serviceLevelDescription:
description: 'Service name. Examples are: UPS Next Day Air, UPS Ground,
UPS Expedited, UPS Worldwide Express Freight'
type: string
maximum: 1
shipDate:
description: "The date the shipment is tendered to UPS for shipping (can
be dropped off at UPS or picked up by UPS). This date may or may not
be the UPS business date. \n \n Valid Format: YYYY-MM-DD"
type: string
maximum: 1
minLength: 10
maxLength: 10
deliveryDate:
description: "Scheduled delivery date. \n \n Valid format: YYYY-MM-DD"
type: string
maximum: 1
minLength: 10
maxLength: 10
commitTime:
description: "Scheduled commit time. \n \n For international shipments the
value always come back from SE (OPSYS data) but for domestic, value may
be used from NRF commit time. \n \n Valid format: HH:MM:SS"
type: string
maximum: 1
minLength: 8
maxLength: 8
deliveryTime:
description: "Scheduled Delivery Time, value may be later then commit time.
\n \n Valid format: HH:MM:SS"
type: string
maximum: 1
minLength: 8
maxLength: 8
deliveryDayOfWeek:
description: "Three character scheduled delivery day of week. \n \n Valid
values: \"MON\",\"TUE\",\"WED\",\"THU\",\"FRI\", \"SAT\""
type: string
maximum: 1
minLength: 3
maxLength: 3
nextDayPickupIndicator:
description: "Returns a \"1\" if the requested shipped on date was changed.
This data is available only for international transactions. \n \n When
this flag is set, WWDTDisclaimer.getNextDayDisclaimer method could be
called to return the next day disclaimer message."
type: string
maximum: 1
minLength: 1
maxLength: 1
saturdayPickupIndicator:
description: "Returns \"1\" if Saturday Pickup is available for an extra
charge otherwise it will return \"0\". \n \n When this flag is set, WWDTDisclaimer.getSaturdayPickupDisclaimer
method could be called to return the Saturday pickup extra charge message"
type: string
maximum: 1
minLength: 1
maxLength: 1
saturdayDeliveryDate:
description: "Delivery date of Saturday Delivery \n \n Valid Format: YYYY-MM-DD"
type: string
maximum: 1
minLength: 10
maxLength: 10
saturdayDeliveryTime:
description: "Delivery time of Saturday deliver \n \n Valid format: HH:MM:SS"
type: string
maximum: 1
minLength: 8
maxLength: 8
serviceRemarksText:
description: Service remarks text. The contents of this field will represent
text that the back end application/function needs to display to clarify
the time in transit calculation.
type: string
maximum: 1
guaranteeIndicator:
description: "Return \"1\" Guaranteed, or \"0\" Not Guaranteed based on
below conditions: \n \n If the ship date, delivery date, and system date
are not within a defined peak date range, and a value for service guarantee
is available in SE (OPSYS data) that will be returned. \n \n If the ship
date or delivery date or system date are within a defined peak date range
and the service is within the list of services to remove guarantees for,
\"0\" wil be returned."
type: string
maximum: 1
minLength: 1
maxLength: 1
totalTransitDays:
description: "Available for International requests. Number of calendar days
from origin location to destination location. TotalTransitDays = BusinessTransitDays
+ RestDaysCount + HolidayCount. \n \n Defaults to 0."
type: integer
maximum: 1
businessTransitDays:
description: Returns the number of UPS business days from origin location
to destination location.
type: integer
maximum: 1
restDaysCount:
description: "Returns the number of rest days encountered at the origin
location. this data is available only for international transactions.
\n \n Defaults to 0."
type: integer
maximum: 1
holidayCount:
description: "Returns the number of holidays encountered at the origin and
destination location, if it effects the time and transit. This data is
available only for international transactions. \n \n Defaults to 0."
type: integer
maximum: 1
delayCount:
description: "Returns the number of delay needed for customs encounter at
the origin or destination location. This data is available only for international
transactions. \n \n Defaults to 0."
type: integer
maximum: 1
pickupDate:
description: "Planned pickup date. \n \n Note: This value may not equal
the shipped on value requested. This could happen when the requested
shipped on date is a holiday or for locations needing 24 hour notice before
a pickup could be made."
type: string
maximum: 1
minLength: 10
maxLength: 10
pickupTime:
description: Latest possible pickup time. This data is available only for
international transactions. If the package was not actually picked by
UPS before this time, the services will not meet the guarantee commitment.
type: string
maximum: 1
minLength: 8
maxLength: 8
cstccutoffTime:
description: Latest time a customer can contact UPS CST to be notified for
requesting a pickup. This data is available only for international transactions.
If customer does not notify UPS for a pickup before this time, the services
will not meet the guarantee commitment.
type: string
maximum: 1
minLength: 8
maxLength: 8
poddate:
description: Returns the date proof of delivery information would be available. This
data is available only for international transactions.
type: string
maximum: 1
minLength: 10
maxLength: 10
poddays:
description: Returns the number of days proof of delivery information will
be available. This data is available only for international transactions.
type: integer
maximum: 1
errors:
type: object
properties:
code:
description: Error code
type: string
message:
description: Error message
type: string