API Reference | ReDoc

Rating

The Rating API is used when rating or shopping a shipment.

Reference


Try out UPS APIs with example requests using Postman. Explore API documentation and sample applications through GitHub.

Run In Postman Open in GitHub

Rating

The Rating API is used when rating or shopping a shipment. For more information on the Rating API, please visit the Product Overview page.

SecurityOAuth2
Request
path Parameters
version
required
string >= 1
Default: "v2409"

Indicates Rate API to display the new release features in Rate API response based on Rate release. See the New section for the latest Rate release.

Valid values:

  • v2409
requestoption
required
string <= 10 characters >= 1

Valid Values:

  • Rate = The server rates (The default Request option is Rate if a Request Option is not provided).
  • Shop = The server validates the shipment, and returns rates for all UPS products from the ShipFrom to the ShipTo addresses.
  • Ratetimeintransit = The server rates with transit time information
  • Shoptimeintransit = The server validates the shipment, and returns rates and transit times for all UPS products from the ShipFrom to the ShipTo addresses.

Rate is the only valid request option for UPS Ground Freight Pricing requests.

query Parameters
additionalinfo
string >= 1

Valid Values: timeintransit = The server rates with transit time information combined with requestoption in URL.Rate is the only valid request option for Ground Freight Pricing requests. Length 15

header Parameters
transId
string

An identifier unique to the request. Length 32

transactionSrc
string
Default: testing

An identifier of the client/source application that is making the request.Length 512

Request Body schema: application/json

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".

<= 1
required
object (RateRequest) <= 1

Rate Request container.

required
object (RateRequest_Request) <= 1

Request container. N/A

SubVersion
string = 4 characters <= 1

Indicates Rate API to display the new release features in Rate API response based on Rate release. See the What's New section for the latest Rate release. Supported values: 1601, 1607, 1701, 1707, 2108, 2205,2407,2409

object (Rating_components-schemas-Request_TransactionReference) <= 1

TransactionReference identifies transactions between client and server.

object (RateRequest_PickupType) <= 1

Pickup Type container tag.

Code
required
string = 2 characters <= 1

Pickup Type Code. Valid values: 01 - Daily Pickup (Default - used when an invalid pickup type code is provided)03 - Customer Counter06 - One Time Pickup19 - Letter Center20 - Air Service CenterLength is not validated. When negotiated rates are requested, 07 (onCallAir) will be ignored.Refer to the Rate Types Table in the Appendix for rate type based on Pickup Type and Customer Classification Code.

Description
string [ 1 .. 35 ] characters <= 1

Pickup Type Description. Ignored if provided in the Request.

object (RateRequest_CustomerClassification) <= 1

Customer classification container. Valid if ShipFrom country or territory is "US"

Code
required
string = 2 characters <= 1

Customer classification code. Valid values:00 - Rates Associated with Shipper Number01 - Daily Rates04 - Retail Rates05 - Regional Rates06 - General List Rates53 - Standard List RatesLength is not validated.If customer classification code is not a valid value please refer to Rate Types Table on page 11.

Description
string [ 1 .. 35 ] characters <= 1

Customer classification description of the code above. Ignored if provided in the Request. Length is not validated.

required
object (RateRequest_Shipment) <= 1

Container for Shipment Information.

OriginRecordTransactionTimestamp
string <= 1

The time that the request was made from the originating system. UTC time down to milliseconds. Example - 2016-07-14T12:01:33.999 Applicable only for HazMat request and with subversion greater than or equal to 1701.

required
object (Shipment_Shipper) <= 1

Shipper container. Information associated with the UPS account number.

required
object (Shipment_ShipTo) <= 1

Ship To Container

object (Shipment_ShipFrom) <= 1

Ship From Container.

object (Shipment_AlternateDeliveryAddress) <= 1

Alternate Delivery Address container. Applies for deliveries to UPS Access Point™ locations.

Required for the following ShipmentIndicationType values:

  • 01 - Hold for Pickup at UPS Access Point™
  • 02 - UPS Access Point™ Delivery
Array of objects (Shipment_ShipmentIndicationType)
object (Shipment_PaymentDetails) <= 1

Payment details container for detailed shipment charges. The two shipment charges that are available for specification are Transportation charges and Duties and Taxes. This container is used for Who Pays What functionality.

object (Shipment_FRSPaymentInformation) <= 1

UPS Ground Freight Pricing (GFP) Payment Information container. Required only for GFP and when the FRSIndicator is present.

object (Shipment_FreightShipmentInformation) <= 1

Container to hold Freight Shipment information.

GoodsNotInFreeCirculationIndicator
string <= 1

Goods Not In Free Circulation indicator. This is an empty tag, any value inside is ignored. This indicator is invalid for a package type of UPS Letter and DocumentsOnly.

object (components-schemas-Shipment_Service) <= 1

Service Container. Only valid with RequestOption = Rate for both Small package and GFP Rating requests.

NumOfPieces
string

Total number of pieces in all pallets. Required for UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday shipments.

object (Shipment_ShipmentTotalWeight) <= 1

Shipment Total Weight Container. This container is only applicable for "ratetimeintransit" and "shoptimeintransit" request options. Required for all international shipments when retreiving time in transit information, including letters and documents shipments.

DocumentsOnlyIndicator
string

Valid values are Document and Non-document. If the indicator is present then the value is Document else Non-Document. Note: Not applicable for FRS rating requests. Empty Tag.

required
Array of objects (components-schemas-Shipment_Package) <= 200
object (Shipment_ShipmentServiceOptions) <= 1

Shipment level Accessorials are included in this container.

object (Shipment_ShipmentRatingOptions) <= 1

Shipment Rating Options container.

object (Shipment_InvoiceLineTotal) <= 1

Container to hold InvoiceLineTotal Information. Required if the shipment is from US/PR Outbound to non US/PR destination with the PackagingType of UPS PAK(04).Required for international shipments when using request option "ratetimeintransit" or "shoptimeintransit".

RatingMethodRequestedIndicator
string <= 1

Presence/Absence Indicator. Any value inside is ignored. RatingMethodRequestedIndicator is an indicator. If present, Billable Weight Calculation method and Rating Method information would be returned in response.

TaxInformationIndicator
string <= 1

Presence/Absence Indicator. Any value inside is ignored. TaxInformationIndicator is an indicator. The Tax related information includes any type of Taxes, corresponding Monetary Values, Total Charges with Taxes and disclaimers (if applicable) would be returned in response. If present, any taxes that may be applicable to a shipment would be returned in response. If this indicator is requested with NegotiatedRatesIndicator, Tax related information, if applicable, would be returned only for Negotiated Rates and not for Published Rates.

object (Shipment_PromotionalDiscountInformation) <= 1

PromotionalDiscountInformation container. This container contains discount information that the customer wants to request each time while placing a shipment.

object (Shipment_DeliveryTimeInformation) <= 1

Container for requesting Time In Transit Information. Required to view time in transit information. Required to view any time in transit information.

MasterCartonIndicator
string <= 1

Presence/Absence Indicator. Any value inside is ignored. MasterCartonIndicator is an indicator and presence implies that shipment is Master Carton type. If present, the shipment will be rated as a Master Carton Type. If this indicator is requested with NegotiatedRatesIndicator, rates would be returned only for Negotiated Rates and not for Published Rates.

WWEShipmentIndicator
string <= 1

Presence/Absence Indicator. Any value inside is ignored. WWEShipmentIndicator is an indicator and presence implies that WWE service details requested for RequestOption=Shop or RequestOption=Shoptimeintransit RequestOption=Shop or RequestOption=Shoptimeintransit

Responses
200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/rating/{version}/{requestoption}
Request samples
application/json
{
  • "RateRequest": {
    }
}
Response samples
application/json
{
  • "RateResponse": {
    }
}

RatingDeprecated

The Rating API is used when rating or shopping a shipment.

SecurityOAuth2
Request
path Parameters
deprecatedVersion
required
string >= 1
Default: "v1"

Indicates Rate API to display the new release features in Rate API response based on Rate release. See the New section for the latest Rate release.

Valid values:

  • v1
  • v1601
  • v1607
  • 1701
  • 1707
  • v2108
  • v2205
requestoption
required
string <= 10 characters >= 1

Valid Values:

  • Rate = The server rates (The default Request option is Rate if a Request Option is not provided).
  • Shop = The server validates the shipment, and returns rates for all UPS products from the ShipFrom to the ShipTo addresses.
  • Ratetimeintransit = The server rates with transit time information
  • Shoptimeintransit = The server validates the shipment, and returns rates and transit times for all UPS products from the ShipFrom to the ShipTo addresses.

Rate is the only valid request option for UPS Ground Freight Pricing requests.

query Parameters
additionalinfo
string >= 1

Valid Values: timeintransit = The server rates with transit time information combined with requestoption in URL.Rate is the only valid request option for Ground Freight Pricing requests. Length 15

header Parameters
transId
string

An identifier unique to the request. Length 32

transactionSrc
string
Default: testing

An identifier of the client/source application that is making the request.Length 512

Request Body schema: application/json

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".

<= 1
required
object (RateRequest) <= 1

Rate Request container.

required
object (RateRequest_Request) <= 1

Request container. N/A

SubVersion
string = 4 characters <= 1

Indicates Rate API to display the new release features in Rate API response based on Rate release. See the What's New section for the latest Rate release. Supported values: 1601, 1607, 1701, 1707, 2108, 2205,2407,2409

object (Rating_components-schemas-Request_TransactionReference) <= 1

TransactionReference identifies transactions between client and server.

object (RateRequest_PickupType) <= 1

Pickup Type container tag.

Code
required
string = 2 characters <= 1

Pickup Type Code. Valid values: 01 - Daily Pickup (Default - used when an invalid pickup type code is provided)03 - Customer Counter06 - One Time Pickup19 - Letter Center20 - Air Service CenterLength is not validated. When negotiated rates are requested, 07 (onCallAir) will be ignored.Refer to the Rate Types Table in the Appendix for rate type based on Pickup Type and Customer Classification Code.

Description
string [ 1 .. 35 ] characters <= 1

Pickup Type Description. Ignored if provided in the Request.

object (RateRequest_CustomerClassification) <= 1

Customer classification container. Valid if ShipFrom country or territory is "US"

Code
required
string = 2 characters <= 1

Customer classification code. Valid values:00 - Rates Associated with Shipper Number01 - Daily Rates04 - Retail Rates05 - Regional Rates06 - General List Rates53 - Standard List RatesLength is not validated.If customer classification code is not a valid value please refer to Rate Types Table on page 11.

Description
string [ 1 .. 35 ] characters <= 1

Customer classification description of the code above. Ignored if provided in the Request. Length is not validated.

required
object (RateRequest_Shipment) <= 1

Container for Shipment Information.

OriginRecordTransactionTimestamp
string <= 1

The time that the request was made from the originating system. UTC time down to milliseconds. Example - 2016-07-14T12:01:33.999 Applicable only for HazMat request and with subversion greater than or equal to 1701.

required
object (Shipment_Shipper) <= 1

Shipper container. Information associated with the UPS account number.

required
object (Shipment_ShipTo) <= 1

Ship To Container

object (Shipment_ShipFrom) <= 1

Ship From Container.

object (Shipment_AlternateDeliveryAddress) <= 1

Alternate Delivery Address container. Applies for deliveries to UPS Access Point™ locations.

Required for the following ShipmentIndicationType values:

  • 01 - Hold for Pickup at UPS Access Point™
  • 02 - UPS Access Point™ Delivery
Array of objects (Shipment_ShipmentIndicationType)
object (Shipment_PaymentDetails) <= 1

Payment details container for detailed shipment charges. The two shipment charges that are available for specification are Transportation charges and Duties and Taxes. This container is used for Who Pays What functionality.

object (Shipment_FRSPaymentInformation) <= 1

UPS Ground Freight Pricing (GFP) Payment Information container. Required only for GFP and when the FRSIndicator is present.

object (Shipment_FreightShipmentInformation) <= 1

Container to hold Freight Shipment information.

GoodsNotInFreeCirculationIndicator
string <= 1

Goods Not In Free Circulation indicator. This is an empty tag, any value inside is ignored. This indicator is invalid for a package type of UPS Letter and DocumentsOnly.

object (components-schemas-Shipment_Service) <= 1

Service Container. Only valid with RequestOption = Rate for both Small package and GFP Rating requests.

NumOfPieces
string

Total number of pieces in all pallets. Required for UPS Worldwide Express Freight and UPS Worldwide Express Freight Midday shipments.

object (Shipment_ShipmentTotalWeight) <= 1

Shipment Total Weight Container. This container is only applicable for "ratetimeintransit" and "shoptimeintransit" request options. Required for all international shipments when retreiving time in transit information, including letters and documents shipments.

DocumentsOnlyIndicator
string

Valid values are Document and Non-document. If the indicator is present then the value is Document else Non-Document. Note: Not applicable for FRS rating requests. Empty Tag.

required
Array of objects (components-schemas-Shipment_Package) <= 200
object (Shipment_ShipmentServiceOptions) <= 1

Shipment level Accessorials are included in this container.

object (Shipment_ShipmentRatingOptions) <= 1

Shipment Rating Options container.

object (Shipment_InvoiceLineTotal) <= 1

Container to hold InvoiceLineTotal Information. Required if the shipment is from US/PR Outbound to non US/PR destination with the PackagingType of UPS PAK(04).Required for international shipments when using request option "ratetimeintransit" or "shoptimeintransit".

RatingMethodRequestedIndicator
string <= 1

Presence/Absence Indicator. Any value inside is ignored. RatingMethodRequestedIndicator is an indicator. If present, Billable Weight Calculation method and Rating Method information would be returned in response.

TaxInformationIndicator
string <= 1

Presence/Absence Indicator. Any value inside is ignored. TaxInformationIndicator is an indicator. The Tax related information includes any type of Taxes, corresponding Monetary Values, Total Charges with Taxes and disclaimers (if applicable) would be returned in response. If present, any taxes that may be applicable to a shipment would be returned in response. If this indicator is requested with NegotiatedRatesIndicator, Tax related information, if applicable, would be returned only for Negotiated Rates and not for Published Rates.

object (Shipment_PromotionalDiscountInformation) <= 1

PromotionalDiscountInformation container. This container contains discount information that the customer wants to request each time while placing a shipment.

object (Shipment_DeliveryTimeInformation) <= 1

Container for requesting Time In Transit Information. Required to view time in transit information. Required to view any time in transit information.

MasterCartonIndicator
string <= 1

Presence/Absence Indicator. Any value inside is ignored. MasterCartonIndicator is an indicator and presence implies that shipment is Master Carton type. If present, the shipment will be rated as a Master Carton Type. If this indicator is requested with NegotiatedRatesIndicator, rates would be returned only for Negotiated Rates and not for Published Rates.

WWEShipmentIndicator
string <= 1

Presence/Absence Indicator. Any value inside is ignored. WWEShipmentIndicator is an indicator and presence implies that WWE service details requested for RequestOption=Shop or RequestOption=Shoptimeintransit RequestOption=Shop or RequestOption=Shoptimeintransit

Responses
200

successful operation

400

Invalid Request

401

Unauthorized Request

403

Blocked Merchant

429

Rate Limit Exceeded

post/rating/{deprecatedVersion}/{requestoption}
Request samples
application/json
{
  • "RateRequest": {
    }
}
Response samples
application/json
{
  • "RateResponse": {
    }
}