UPSFreightRates Class

Properties   Methods   Events   Config Settings   Errors  

Provides UPS Freight Rates service.

Syntax

class dshippingsdk.UPSFreightRates

Remarks

The UPSFreightRates class provides a way to retrieve rates for freight shipments. To use the class first set requested_service to the service for which rates will be retrieved. Then specify the sender, recipient, and shipment information and call get_rates. Upon response charges, total_charge, billable_weight, and dimensional_weight will be populated. For instance:

component.UPSServer = "https://wwwcie.ups.com/api/freight/" component.UPSAuthorizationToken = "Bearer token..." component.UPSAccountNumber = "000000" component.SenderName = "Developer Test 1" component.SenderAddress1 = "101 Developer Way" component.SenderCity = "Richmond" component.SenderState = "VA" component.SenderZipCode = "23224" component.SenderCountryCode = "US" component.RecipientName = "Consignee Test 1" component.RecipientAddress1 = "1000 Consignee Street" component.RecipientCity = "Allanton" component.RecipientState = "MO" component.RecipientZipCode = "63001" component.RecipientCountryCode = "US" component.PayorType = ptSender component.HandlingUnit = "SKD:1" component.CommodityCount = 1 component.CommodityDescription(0) = "LCD TVS" component.CommodityFreightClass(0) = "77.5" component.CommodityWeight(0) = "200" component.CommodityFreightNMFC(0) = "132680" component.CommodityFreightNMFCSub(0) = "02" component.CommodityNumberOfPieces(0) = 20 component.CommodityValue(0) = "100" component.GetRates Debug.Print ("Total Charge: " & component.TotalCharge) Debug.Print ("Billable Weight: " & component.BillableWeight) Debug.Print ("Dimensional Weight: " & component.DimensionalWeight) Dim i As Integer For i = 0 To component.ChargeCount - 1 Debug.Print (component.ChargeType(0) & ": " & component.ChargeValue()) Next i

Property List

The following is the full list of the properties of the class with short descriptions. Click on the links for further details.

Method List

The following is the full list of the methods of the class with short descriptions. Click on the links for further details.

Event List

The following is the full list of the events fired by the class with short descriptions. Click on the links for further details.

Config Settings

The following is a list of config settings for the class with short descriptions. Click on the links for further details.

billable_weight Property

Represents the billable weight associated with the shipment.

Syntax

def get_billable_weight() -> str: ...

billable_weight = property(get_billable_weight, None)

Default Value

""

Remarks

This property is read-only.

charge_count Property

The number of records in the Charge arrays.

Syntax

def get_charge_count() -> int: ...
def set_charge_count(value: int) -> None: ...

charge_count = property(get_charge_count, set_charge_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• charge_description
• charge_type
• charge_value

The array indices start at 0 and end at charge_count - 1.

charge_type Property

Indicates the type of the charge.

Syntax

def get_charge_type(charge_index: int) -> str: ...
def set_charge_type(charge_index: int, value: str) -> None: ...

Default Value

""

Remarks

Indicates the type of the charge. A partial list of possible values are:

The charge_index parameter specifies the index of the item in the array. The size of the array is controlled by the charge_count property.

charge_description Property

The description of the rate.

Syntax

def get_charge_description(charge_index: int) -> str: ...
def set_charge_description(charge_index: int, value: str) -> None: ...

Default Value

""

Remarks

The description of the rate. The text description is provided by the class based on the value in charge_type. If a description is not know for the charge_type this property will hold an empty string. Possible values are:

The charge_index parameter specifies the index of the item in the array. The size of the array is controlled by the charge_count property.

charge_value Property

The value of the charge type specified by ChargeType .

Syntax

def get_charge_value(charge_index: int) -> str: ...
def set_charge_value(charge_index: int, value: str) -> None: ...

Default Value

""

Remarks

The value of the charge type specified by charge_type.

The charge_index parameter specifies the index of the item in the array. The size of the array is controlled by the charge_count property.

cod_payor_type Property

The type of payment that will be used for the COD payment.

Syntax

def get_cod_payor_type() -> int: ...
def set_cod_payor_type(value: int) -> None: ...

cod_payor_type = property(get_cod_payor_type, set_cod_payor_type)

Default Value

0

Remarks

This property specifies the type of COD payment. Possible values are:

cod_total_amount Property

The total amount of additional fees.

Syntax

def get_cod_total_amount() -> str: ...
def set_cod_total_amount(value: str) -> None: ...

cod_total_amount = property(get_cod_total_amount, set_cod_total_amount)

Default Value

""

Remarks

UPS Freight handles your payment collections upon delivery and sends the payment to you (if applicable) for an additional charge.

cod_type Property

The code that indicates the type of funds that will be used for the COD payment.

Syntax

def get_cod_type() -> int: ...
def set_cod_type(value: int) -> None: ...

cod_type = property(get_cod_type, set_cod_type)

Default Value

0

Remarks

This property specifies the type of COD requested. Possible values are:

commodity_count Property

The number of records in the Commodity arrays.

Syntax

def get_commodity_count() -> int: ...
def set_commodity_count(value: int) -> None: ...

commodity_count = property(get_commodity_count, set_commodity_count)

Default Value

0

Remarks

This property controls the size of the following arrays:

• commodity_description
• commodity_freight_class
• commodity_freight_is_hazardous
• commodity_freight_nmfc
• commodity_freight_nmfc_sub
• commodity_freight_packaging_type
• commodity_number_of_pieces
• commodity_value
• commodity_weight

The array indices start at 0 and end at commodity_count - 1.

commodity_description Property

Complete and accurate description of this commodity line item.

Syntax

def get_commodity_description(commodity_index: int) -> str: ...
def set_commodity_description(commodity_index: int, value: str) -> None: ...

Default Value

""

Remarks

Complete and accurate description of this commodity line item.

It is applicable to all international forms. Optional for Partial Invoice and required for the rest of form types.

Specific description of the type of equipment and its intended use is required. Clearance delays may result if the contents are not completely and accurately described. Vague description will not be accepted by Customs. Only a portion of this field will print on the label.

For FedEx, if the shipment contains documents only (i.e., Documents is set to True), then the commodity_description has to be set to an approved value. The following table lists document descriptions approved by U.S. Customs.

The commodity_index parameter specifies the index of the item in the array. The size of the array is controlled by the commodity_count property.

commodity_freight_class Property

Indicates the freight class of the commodity.

Syntax

def get_commodity_freight_class(commodity_index: int) -> str: ...
def set_commodity_freight_class(commodity_index: int, value: str) -> None: ...

Default Value

""

Remarks

Indicates the freight class of the commodity.

The following table lists freight classes available from UPS freight services.

NOTE: This field is only applicable to UPS freight.

The commodity_index parameter specifies the index of the item in the array. The size of the array is controlled by the commodity_count property.

commodity_freight_is_hazardous Property

Identifies if the Commodity item is hazardous.

Syntax

def get_commodity_freight_is_hazardous(commodity_index: int) -> bool: ...
def set_commodity_freight_is_hazardous(commodity_index: int, value: bool) -> None: ...

Default Value

FALSE

Remarks

Identifies if the Commodity item is hazardous.

NOTE: This field is only applicable to UPS freight.

The commodity_index parameter specifies the index of the item in the array. The size of the array is controlled by the commodity_count property.

commodity_freight_nmfc Property

Identifies the National Motor Freight Classification numbers.

Syntax

def get_commodity_freight_nmfc(commodity_index: int) -> str: ...
def set_commodity_freight_nmfc(commodity_index: int, value: str) -> None: ...

Default Value

""

Remarks

Identifies the National Motor Freight Classification numbers.

NOTE: This field is only applicable to UPS freight.

The commodity_index parameter specifies the index of the item in the array. The size of the array is controlled by the commodity_count property.

commodity_freight_nmfc_sub Property

Identifies the sub code of National Motor Freight Classification numbers.

Syntax

def get_commodity_freight_nmfc_sub(commodity_index: int) -> str: ...
def set_commodity_freight_nmfc_sub(commodity_index: int, value: str) -> None: ...

Default Value

""

Remarks

Identifies the sub code of National Motor Freight Classification numbers.

NOTE: This field is only applicable to UPS freight.

The commodity_index parameter specifies the index of the item in the array. The size of the array is controlled by the commodity_count property.

commodity_freight_packaging_type Property

Identifies the Commodity item's packaging type.

Syntax

def get_commodity_freight_packaging_type(commodity_index: int) -> int: ...
def set_commodity_freight_packaging_type(commodity_index: int, value: int) -> None: ...

Default Value

0

Remarks

Identifies the Commodity item's packaging type. Possible values are:

NOTE: This field is only applicable to UPS freight.

The commodity_index parameter specifies the index of the item in the array. The size of the array is controlled by the commodity_count property.

commodity_number_of_pieces Property

The total number of packages, cartons, or containers for the commodity line item.

Syntax

def get_commodity_number_of_pieces(commodity_index: int) -> int: ...
def set_commodity_number_of_pieces(commodity_index: int, value: int) -> None: ...

Default Value

1

Remarks

The total number of packages, cartons, or containers for the commodity line item.

In UPS, it is required and applicable to CO only.

In FedEx, if the Documents is set to False in ship request, the commodity_number_of_pieces is required to be entered for each commodity item included in an international shipment. At least one occurrence is required for international dutiable (non-documents) shipments.

This property is not applicable to USPS.

The commodity_index parameter specifies the index of the item in the array. The size of the array is controlled by the commodity_count property.

commodity_value Property

The value of an individual item being shipped.

Syntax

def get_commodity_value(commodity_index: int) -> str: ...
def set_commodity_value(commodity_index: int, value: str) -> None: ...

Default Value

""

Remarks

The value of an individual item being shipped. This should be provided for each item contained in the package being shipped. This property provides the value of the set of items. If the item is 2 boxes of 50 pens and the value of each box is $10.00, "20.00" (2 boxes x $10.00) should be entered. If the value of each pen is .25, then "25.00" (100 pens x .25) should be entered.

This property is only applicable to USPS and UPS freight.

Note: For USPS, the maximum value for this property is "99999.99".

Note: For UPS freight, the maximum value for this property is "99999999999999.99".

The commodity_index parameter specifies the index of the item in the array. The size of the array is controlled by the commodity_count property.

commodity_weight Property

The shipping weight of this commodity line item, including containers, for each commodity with a separate Harmonized Tariff Code.

Syntax

def get_commodity_weight(commodity_index: int) -> str: ...
def set_commodity_weight(commodity_index: int, value: str) -> None: ...

Default Value

"0.00"

Remarks

The shipping weight of this commodity line item, including containers, for each commodity with a separate Harmonized Tariff Code. This weight does not include carrier equipment.

For FedEx, if the shipment contains non-documents item(s) (i.e., the Documents is set to False), the commodity_weight is required to be entered for each commodity line item included in shipment. At least one commodity occurrence is required for international dutiable (non-documents) shipments.

For UPS, this is required and applicable to CO and SED forms only .

When using USPS and postage_provider is set to ppNone, the format of this property must be "XX lbs YY oz", where XX is the number of pounds and YY is the number of ounces.

However, in USPS, if postage_provider is set to ppEndicia, then the format must be one explicit decimal position in ounces (i.e. N.N formatting).

The commodity_index parameter specifies the index of the item in the array. The size of the array is controlled by the commodity_count property.

dimensional_weight Property

Represents the dimensional weight associated with the shipment.

Syntax

def get_dimensional_weight() -> str: ...

dimensional_weight = property(get_dimensional_weight, None)

Default Value

""

Remarks

The dimensional weight as calculated by the server and returned in the response.

This property is read-only.

firewall_auto_detect Property

This property tells the class whether or not to automatically detect and use firewall system settings, if available.

Syntax

def get_firewall_auto_detect() -> bool: ...
def set_firewall_auto_detect(value: bool) -> None: ...

firewall_auto_detect = property(get_firewall_auto_detect, set_firewall_auto_detect)

Default Value

FALSE

Remarks

This property tells the class whether or not to automatically detect and use firewall system settings, if available.

firewall_type Property

This property determines the type of firewall to connect through.

Syntax

def get_firewall_type() -> int: ...
def set_firewall_type(value: int) -> None: ...

firewall_type = property(get_firewall_type, set_firewall_type)

Default Value

0

Remarks

This property determines the type of firewall to connect through. The applicable values are as follows:

firewall_host Property

This property contains the name or IP address of firewall (optional).

Syntax

def get_firewall_host() -> str: ...
def set_firewall_host(value: str) -> None: ...

firewall_host = property(get_firewall_host, set_firewall_host)

Default Value

""

Remarks

This property contains the name or IP address of firewall (optional). If a firewall_host is given, the requested connections will be authenticated through the specified firewall when connecting.

If this property is set to a Domain Name, a DNS request is initiated. Upon successful termination of the request, this property is set to the corresponding address. If the search is not successful, the class fails with an error.

firewall_password Property

This property contains a password if authentication is to be used when connecting through the firewall.

Syntax

def get_firewall_password() -> str: ...
def set_firewall_password(value: str) -> None: ...

firewall_password = property(get_firewall_password, set_firewall_password)

Default Value

""

Remarks

This property contains a password if authentication is to be used when connecting through the firewall. If firewall_host is specified, the firewall_user and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

firewall_port Property

This property contains the transmission control protocol (TCP) port for the firewall Host .

Syntax

def get_firewall_port() -> int: ...
def set_firewall_port(value: int) -> None: ...

firewall_port = property(get_firewall_port, set_firewall_port)

Default Value

0

Remarks

This property contains the transmission control protocol (TCP) port for the firewall firewall_host. See the description of the firewall_host property for details.

Note: This property is set automatically when firewall_type is set to a valid value. See the description of the firewall_type property for details.

firewall_user Property

This property contains a user name if authentication is to be used connecting through a firewall.

Syntax

def get_firewall_user() -> str: ...
def set_firewall_user(value: str) -> None: ...

firewall_user = property(get_firewall_user, set_firewall_user)

Default Value

""

Remarks

This property contains a user name if authentication is to be used connecting through a firewall. If the firewall_host is specified, this property and firewall_password properties are used to connect and authenticate to the given firewall. If the authentication fails, the class fails with an error.

handling_unit Property

Describe the Handling Units (Movable Pieces) in this Shipment.

Syntax

def get_handling_unit() -> str: ...
def set_handling_unit(value: str) -> None: ...

handling_unit = property(get_handling_unit, set_handling_unit)

Default Value

""

Remarks

over_seas_leg_height Property

The height of the shipment.

Syntax

def get_over_seas_leg_height() -> int: ...
def set_over_seas_leg_height(value: int) -> None: ...

over_seas_leg_height = property(get_over_seas_leg_height, set_over_seas_leg_height)

Default Value

0

Remarks

The height of the shipment. For shipments with destinations of Hawaii, Alaska or Puerto Rico, you must specify this property or the TotalShipmentCubicFeet before shipping.

over_seas_leg_length Property

The length of the shipment.

Syntax

def get_over_seas_leg_length() -> int: ...
def set_over_seas_leg_length(value: int) -> None: ...

over_seas_leg_length = property(get_over_seas_leg_length, set_over_seas_leg_length)

Default Value

0

Remarks

The length of the shipment. For shipments with destinations of Hawaii, Alaska or Puerto Rico, you must specify this property or the TotalShipmentCubicFeet before shipping.

over_seas_leg_price_per_cubic_foot Property

The price per CubicFoot.

Syntax

def get_over_seas_leg_price_per_cubic_foot() -> str: ...
def set_over_seas_leg_price_per_cubic_foot(value: str) -> None: ...

over_seas_leg_price_per_cubic_foot = property(get_over_seas_leg_price_per_cubic_foot, set_over_seas_leg_price_per_cubic_foot)

Default Value

""

Remarks

The price per CubicFoot.

over_seas_leg_price_per_cwt Property

Price per Hundredweight.

Syntax

def get_over_seas_leg_price_per_cwt() -> str: ...
def set_over_seas_leg_price_per_cwt(value: str) -> None: ...

over_seas_leg_price_per_cwt = property(get_over_seas_leg_price_per_cwt, set_over_seas_leg_price_per_cwt)

Default Value

""

Remarks

Price per Hundredweight. For shipments with Puerto Rico as a destination, you may specify this amount before shipping.

over_seas_leg_total_cubic_feet Property

Total cubic weight of the shipment, obtained by multiplying width by height by depth.

Syntax

def get_over_seas_leg_total_cubic_feet() -> str: ...
def set_over_seas_leg_total_cubic_feet(value: str) -> None: ...

over_seas_leg_total_cubic_feet = property(get_over_seas_leg_total_cubic_feet, set_over_seas_leg_total_cubic_feet)

Default Value

""

Remarks

Total cubic weight of the shipment, obtained by multiplying width by height by depth. For shipments with destinations of Hawaii, Alaska or Puerto Rico, you must specify this amount before shipping.

over_seas_leg_width Property

The width of the shipment.

Syntax

def get_over_seas_leg_width() -> int: ...
def set_over_seas_leg_width(value: int) -> None: ...

over_seas_leg_width = property(get_over_seas_leg_width, set_over_seas_leg_width)

Default Value

0

Remarks

The width of the shipment. For shipments with destinations of Hawaii, Alaska or Puerto Rico, you must specify this property or the TotalShipmentCubicFeet before shipping.

payor_address1 Property

Street name.

Syntax

def get_payor_address1() -> str: ...
def set_payor_address1(value: str) -> None: ...

payor_address1 = property(get_payor_address1, set_payor_address1)

Default Value

""

Remarks

Street name. In a ship request, this is required to be provided for both sender and recipient. In all other requests, it is required for a valid physical address. Combination of payor_address1 and payor_address2 should not exceed 35 characters.

payor_address2 Property

A specific detail on the address (such as building, suite, apartment, floor number etc.

Syntax

def get_payor_address2() -> str: ...
def set_payor_address2(value: str) -> None: ...

payor_address2 = property(get_payor_address2, set_payor_address2)

Default Value

""

Remarks

A specific detail on the address (such as building, suite, apartment, floor number etc.). This is optional. Combination of payor_address1 and payor_address2 should not exceed 35 characters.

payor_city Property

Name of city, town, etc.

Syntax

def get_payor_city() -> str: ...
def set_payor_city(value: str) -> None: ...

payor_city = property(get_payor_city, set_payor_city)

Default Value

""

Remarks

Name of city, town, etc.

payor_country_code Property

The country code for the payor of the shipment, or duties and taxes.

Syntax

def get_payor_country_code() -> str: ...
def set_payor_country_code(value: str) -> None: ...

payor_country_code = property(get_payor_country_code, set_payor_country_code)

Default Value

"US"

Remarks

The country code for the payor of the shipment, or duties and taxes.

When shipping via FedEx Express, the payor_country_code is required to be provided in the ship request only if payor_type is set to 'RECIPIENT' or 'THIRDPARTY'. For FedEx Ground shipments, the payor_country_code is required only if payor_type is set to 'THIRDPARTY'.

For UPS, this should be the same as it was entered in the UPS system when this account was set up. In domestic shipments, it will always default to US.

payor_name Property

Identifies the payor's name.

Syntax

def get_payor_name() -> str: ...
def set_payor_name(value: str) -> None: ...

payor_name = property(get_payor_name, set_payor_name)

Default Value

""

Remarks

Identifies the payor's name.

payor_name is required only if payor_type is set to 'THIRDPARTY'.

Note: This property is only applicable to UPSFreightRates and UPSFreightShip.

payor_type Property

Method of payment for shipment, or duties and taxes.

Syntax

def get_payor_type() -> int: ...
def set_payor_type(value: int) -> None: ...

payor_type = property(get_payor_type, set_payor_type)

Default Value

0

Remarks

Method of payment for shipment, or duties and taxes. This is required to be provided in a ship request. Valid payment types are:

The COLLECT payment type is only supported in FedEx Ground services. The CONSIGNEE type is only supported in UPS service.

For FedEx, when this property is set to a value other than 0 (ptSender), the payor_account_number and payor_country_code are required to be provided in the request as well. Otherwise, those will default to fed_ex_account_number and sender_country_code.

For UPS, when set to ptSender, the payor_account_number is automatically set to ups_account_number. When ptRecipient is specified, payor_account_number and payor_zip_code are required to be provided in the request. For return international shipments, this option is invalid for transportation charges. And, when ptThirdParty has been specified, the payor_account_number, payor_zip_code and payor_country_code are required to be provided in the request. When ptConsignee is specified, it indicates that UPS Consignee Billing option is selected, no other fields need to be set. ptConsignee only applies to US/PR and PR/US shipment origins and destination.

payor_state Property

State or province code.

Syntax

def get_payor_state() -> str: ...
def set_payor_state(value: str) -> None: ...

payor_state = property(get_payor_state, set_payor_state)

Default Value

""

Remarks

State or province code. This is the identifying abbreviation for US state, Canada province, etc. In a ship request, this is required to be provided for both sender and recipient (where applicable). Format and presence of this field will vary, depending on country.

payor_zip_code Property

Payor's postal code (if applicable).

Syntax

def get_payor_zip_code() -> str: ...
def set_payor_zip_code(value: str) -> None: ...

payor_zip_code = property(get_payor_zip_code, set_payor_zip_code)

Default Value

""

Remarks

Payor's postal code (if applicable).

This is only applicable to UPS and is the corresponding postal code of the UPS payor_account_number's pickup address. This should be the same as it was entered in the UPS system when this account was set up.

It can be provided in a ship request only if the payor_type is set to 1 (RECIPIENT) or 2 (THIRDPARTY).

Maximum length: 10.

proxy_auth_scheme Property

This property is used to tell the class which type of authorization to perform when connecting to the proxy.

Syntax

def get_proxy_auth_scheme() -> int: ...
def set_proxy_auth_scheme(value: int) -> None: ...

proxy_auth_scheme = property(get_proxy_auth_scheme, set_proxy_auth_scheme)

Default Value

0

Remarks

This property is used to tell the class which type of authorization to perform when connecting to the proxy. This is used only when the proxy_user and proxy_password properties are set.

proxy_auth_scheme should be set to authNone (3) when no authentication is expected.

By default, proxy_auth_scheme is authBasic (0), and if the proxy_user and proxy_password properties are set, the component will attempt basic authentication.

If proxy_auth_scheme is set to authDigest (1), digest authentication will be attempted instead.

If proxy_auth_scheme is set to authProprietary (2), then the authorization token will not be generated by the class. Look at the configuration file for the class being used to find more information about manually setting this token.

If proxy_auth_scheme is set to authNtlm (4), NTLM authentication will be used.

For security reasons, setting this property will clear the values of proxy_user and proxy_password.

proxy_auto_detect Property

This property tells the class whether or not to automatically detect and use proxy system settings, if available.

Syntax

def get_proxy_auto_detect() -> bool: ...
def set_proxy_auto_detect(value: bool) -> None: ...

proxy_auto_detect = property(get_proxy_auto_detect, set_proxy_auto_detect)

Default Value

FALSE

Remarks

This property tells the class whether or not to automatically detect and use proxy system settings, if available. The default value is False.

proxy_password Property

This property contains a password if authentication is to be used for the proxy.

Syntax

def get_proxy_password() -> str: ...
def set_proxy_password(value: str) -> None: ...

proxy_password = property(get_proxy_password, set_proxy_password)

Default Value

""

Remarks

This property contains a password if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

proxy_port Property

This property contains the Transmission Control Protocol (TCP) port for the proxy Server (default 80).

Syntax

def get_proxy_port() -> int: ...
def set_proxy_port(value: int) -> None: ...

proxy_port = property(get_proxy_port, set_proxy_port)

Default Value

80

Remarks

This property contains the Transmission Control Protocol (TCP) port for the proxy proxy_server (default 80). See the description of the proxy_server property for details.

proxy_server Property

If a proxy Server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

Syntax

def get_proxy_server() -> str: ...
def set_proxy_server(value: str) -> None: ...

proxy_server = property(get_proxy_server, set_proxy_server)

Default Value

""

Remarks

If a proxy proxy_server is given, then the HTTP request is sent to the proxy instead of the server otherwise specified.

If the proxy_server property is set to a domain name, a DNS request is initiated. Upon successful termination of the request, the proxy_server property is set to the corresponding address. If the search is not successful, an error is returned.

proxy_ssl Property

This property determines when to use a Secure Sockets Layer (SSL) for the connection to the proxy.

Syntax

def get_proxy_ssl() -> int: ...
def set_proxy_ssl(value: int) -> None: ...

proxy_ssl = property(get_proxy_ssl, set_proxy_ssl)

Default Value

0

Remarks

This property determines when to use a Secure Sockets Layer (SSL) for the connection to the proxy. The applicable values are as follows:

proxy_user Property

This property contains a username if authentication is to be used for the proxy.

Syntax

def get_proxy_user() -> str: ...
def set_proxy_user(value: str) -> None: ...

proxy_user = property(get_proxy_user, set_proxy_user)

Default Value

""

Remarks

This property contains a username if authentication is to be used for the proxy.

If proxy_auth_scheme is set to Basic Authentication, the proxy_user and proxy_password properties are Base64 encoded and the proxy authentication token will be generated in the form Basic [encoded-user-password].

If proxy_auth_scheme is set to Digest Authentication, the proxy_user and proxy_password properties are used to respond to the Digest Authentication challenge from the server.

If proxy_auth_scheme is set to NTLM Authentication, the proxy_user and proxy_password properties are used to authenticate through NTLM negotiation.

recipient_address1 Property

Street name.

Syntax

def get_recipient_address1() -> str: ...
def set_recipient_address1(value: str) -> None: ...

recipient_address1 = property(get_recipient_address1, set_recipient_address1)

Default Value

""

Remarks

Street name. In a ship request, this is required to be provided for both sender and recipient. In all other requests, it is required for a valid physical address. For UPS recipient_address1 should not exceed 35 characters.

recipient_address2 Property

A specific detail on the address (such as building, suite, apartment, floor number etc.

Syntax

def get_recipient_address2() -> str: ...
def set_recipient_address2(value: str) -> None: ...

recipient_address2 = property(get_recipient_address2, set_recipient_address2)

Default Value

""

Remarks

A specific detail on the address (such as building, suite, apartment, floor number etc.). This is optional. For UPS recipient_address2 should not exceed 35 characters.

recipient_address_flags Property

Various flags that denote information about the address.

Syntax

def get_recipient_address_flags() -> int: ...
def set_recipient_address_flags(value: int) -> None: ...

recipient_address_flags = property(get_recipient_address_flags, set_recipient_address_flags)

Default Value

0

Remarks

Various flags that denote information about the address.

recipient_city Property

Name of city, town, etc.

Syntax

def get_recipient_city() -> str: ...
def set_recipient_city(value: str) -> None: ...

recipient_city = property(get_recipient_city, set_recipient_city)

Default Value

""

Remarks

Name of city, town, etc. In a ship request, this is required to be provided for both sender and recipient.

recipient_country_code Property

Country code.

Syntax

def get_recipient_country_code() -> str: ...
def set_recipient_country_code(value: str) -> None: ...

recipient_country_code = property(get_recipient_country_code, set_recipient_country_code)

Default Value

"US"

Remarks

Country code. This identifies a country. In a ship request, this is required to be provided for both sender and recipient. Maximum length: 2.

Here is a list of country names and their codes. Code is the value that has to be provided in all requests sent where country code is to be entered. Note that with USPS you can also specify the full country name here.

* Not supported by USPS

** Has multiple values, the values used for USPS are below

recipient_state Property

State or province code.

Syntax

def get_recipient_state() -> str: ...
def set_recipient_state(value: str) -> None: ...

recipient_state = property(get_recipient_state, set_recipient_state)

Default Value

""

Remarks

State or province code. This is the identifying abbreviation for US state, Canada province, etc. In a ship request, this is required to be provided for both sender and recipient (where applicable). Format and presence of this field will vary, depending on country.

recipient_zip_code Property

Postal code.

Syntax

def get_recipient_zip_code() -> str: ...
def set_recipient_zip_code(value: str) -> None: ...

recipient_zip_code = property(get_recipient_zip_code, set_recipient_zip_code)

Default Value

""

Remarks

Postal code. This is identification of a region (usually small) for mail/package delivery. Format and presence of this field will vary, depending on country.

In a ship request, this is required to be provided for both sender and recipient. In all other requests, this element is required if both recipient_city and recipient_state are not present.

Valid characters: A-Z; 0-9; a-z. Maximum length: 16.

recipient_name Property

Identifies the recipient's name or company name.

Syntax

def get_recipient_name() -> str: ...
def set_recipient_name(value: str) -> None: ...

recipient_name = property(get_recipient_name, set_recipient_name)

Default Value

""

Remarks

The recipient's name or company name.

requested_service Property

The service selected for the shipment.

Syntax

def get_requested_service() -> int: ...
def set_requested_service(value: int) -> None: ...

requested_service = property(get_requested_service, set_requested_service)

Default Value

0

Remarks

Specifies the service for the shipment.

Valid values for UPS Freight are:

sender_address1 Property

Street name.

Syntax

def get_sender_address1() -> str: ...
def set_sender_address1(value: str) -> None: ...

sender_address1 = property(get_sender_address1, set_sender_address1)

Default Value

""

Remarks

Street name. In a ship request, this is required to be provided for both sender and recipient. In all other requests, it is required for a valid physical address. For UPS sender_address1 should not exceed 35 characters.

sender_address2 Property

A specific detail on the address (such as building, suite, apartment, floor number etc.

Syntax

def get_sender_address2() -> str: ...
def set_sender_address2(value: str) -> None: ...

sender_address2 = property(get_sender_address2, set_sender_address2)

Default Value

""

Remarks

A specific detail on the address (such as building, suite, apartment, floor number etc.). This is optional. For UPS sender_address2 should not exceed 35 characters.

sender_city Property

Name of city, town, etc.

Syntax

def get_sender_city() -> str: ...
def set_sender_city(value: str) -> None: ...

sender_city = property(get_sender_city, set_sender_city)

Default Value

""

Remarks

Name of city, town, etc. In a ship request, this is required to be provided for both sender and recipient.

sender_country_code Property

Country code.

Syntax

def get_sender_country_code() -> str: ...
def set_sender_country_code(value: str) -> None: ...

sender_country_code = property(get_sender_country_code, set_sender_country_code)

Default Value

"US"

Remarks

Country code. This identifies a country. In a ship request, this is required to be provided for both sender and recipient. Maximum length: 2.

Here is a list of country names and their codes. Code is the value that has to be provided in all requests sent where country code is to be entered. Note that with USPS you can also specify the full country name here.

* Not supported by USPS

** Has multiple values, the values used for USPS are below

sender_state Property

State or province code.

Syntax

def get_sender_state() -> str: ...
def set_sender_state(value: str) -> None: ...

sender_state = property(get_sender_state, set_sender_state)

Default Value

""

Remarks

State or province code. This is the identifying abbreviation for US state, Canada province, etc. In a ship request, this is required to be provided for both sender and recipient (where applicable). Format and presence of this field will vary, depending on country.

sender_zip_code Property

Postal code.

Syntax

def get_sender_zip_code() -> str: ...
def set_sender_zip_code(value: str) -> None: ...

sender_zip_code = property(get_sender_zip_code, set_sender_zip_code)

Default Value

""

Remarks

Postal code. This is identification of a region (usually small) for mail/package delivery. Format and presence of this field will vary, depending on country.

In a ship request, this is required to be provided for both sender and recipient. In all other requests, this element is required if both sender_city and sender_state are not present.

Valid characters: A-Z; 0-9; a-z. Maximum length: 16.

sender_name Property

Identifies the sender's locations name or company name.

Syntax

def get_sender_name() -> str: ...
def set_sender_name(value: str) -> None: ...

sender_name = property(get_sender_name, set_sender_name)

Default Value

""

Remarks

ssl_accept_server_cert_encoded Property

This is the certificate (PEM/Base64 encoded).

Syntax

def get_ssl_accept_server_cert_encoded() -> bytes: ...
def set_ssl_accept_server_cert_encoded(value: bytes) -> None: ...

ssl_accept_server_cert_encoded = property(get_ssl_accept_server_cert_encoded, set_ssl_accept_server_cert_encoded)

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_accept_server_cert_store and ssl_accept_server_cert_subject properties also may be used to specify a certificate.

When ssl_accept_server_cert_encoded is set, a search is initiated in the current ssl_accept_server_cert_store for the private key of the certificate. If the key is found, ssl_accept_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_accept_server_cert_subject is set to an empty string.

ssl_cert_encoded Property

This is the certificate (PEM/Base64 encoded).

Syntax

def get_ssl_cert_encoded() -> bytes: ...
def set_ssl_cert_encoded(value: bytes) -> None: ...

ssl_cert_encoded = property(get_ssl_cert_encoded, set_ssl_cert_encoded)

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_cert_store and ssl_cert_subject properties also may be used to specify a certificate.

When ssl_cert_encoded is set, a search is initiated in the current ssl_cert_store for the private key of the certificate. If the key is found, ssl_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_cert_subject is set to an empty string.

ssl_cert_store Property

This is the name of the certificate store for the client certificate.

Syntax

def get_ssl_cert_store() -> bytes: ...
def set_ssl_cert_store(value: bytes) -> None: ...

ssl_cert_store = property(get_ssl_cert_store, set_ssl_cert_store)

Default Value

"MY"

Remarks

This is the name of the certificate store for the client certificate.

The ssl_cert_store_type property denotes the type of the certificate store specified by ssl_cert_store. If the store is password protected, specify the password in ssl_cert_store_password.

ssl_cert_store is used in conjunction with the ssl_cert_subject property to specify client certificates. If ssl_cert_store has a value, and ssl_cert_subject or ssl_cert_encoded is set, a search for a certificate is initiated. Please see the ssl_cert_subject property for details.

Designations of certificate stores are platform dependent.

The following designations are the most common User and Machine certificate stores in Windows:

When the certificate store type is PFXFile, this property must be set to the name of the file. When the type is PFXBlob, the property must be set to the binary contents of a PFX file (i.e., PKCS#12 certificate store).

ssl_cert_store_password Property

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

Syntax

def get_ssl_cert_store_password() -> str: ...
def set_ssl_cert_store_password(value: str) -> None: ...

ssl_cert_store_password = property(get_ssl_cert_store_password, set_ssl_cert_store_password)

Default Value

""

Remarks

If the type of certificate store requires a password, this property is used to specify the password needed to open the certificate store.

ssl_cert_store_type Property

This is the type of certificate store for this certificate.

Syntax

def get_ssl_cert_store_type() -> int: ...
def set_ssl_cert_store_type(value: int) -> None: ...

ssl_cert_store_type = property(get_ssl_cert_store_type, set_ssl_cert_store_type)

Default Value

0

Remarks

This is the type of certificate store for this certificate.

The class supports both public and private keys in a variety of formats. When the cstAuto value is used, the class will automatically determine the type. This property can take one of the following values:

ssl_cert_subject Property

This is the subject of the certificate used for client authentication.

Syntax

def get_ssl_cert_subject() -> str: ...
def set_ssl_cert_subject(value: str) -> None: ...

ssl_cert_subject = property(get_ssl_cert_subject, set_ssl_cert_subject)

Default Value

""

Remarks

This is the subject of the certificate used for client authentication.

This property must be set after all other certificate properties are set. When this property is set, a search is performed in the current certificate store to locate a certificate with a matching subject.

If a matching certificate is found, the property is set to the full subject of the matching certificate.

If an exact match is not found, the store is searched for subjects containing the value of the property.

If a match is still not found, the property is set to an empty string, and no certificate is selected.

The special value "*" picks a random certificate in the certificate store.

The certificate subject is a comma-separated list of distinguished name fields and values. For instance, "CN=www.server.com, OU=test, C=US, E=support@nsoftware.com". Common fields and their meanings are as follows:

If a field value contains a comma, it must be quoted.

ssl_provider Property

This specifies the SSL/TLS implementation to use.

Syntax

def get_ssl_provider() -> int: ...
def set_ssl_provider(value: int) -> None: ...

ssl_provider = property(get_ssl_provider, set_ssl_provider)

Default Value

0

Remarks

This property specifies the SSL/TLS implementation to use. In most cases the default value of 0 (Automatic) is recommended and should not be changed. When set to 0 (Automatic) the class will select whether to use the platform implementation or the internal implementation depending on the operating system as well as the TLS version being used.

Possible values are:

In most cases using the default value (Automatic) is recommended. The class will select a provider depending on the current platform.

When Automatic is selected, on Windows the class will use the platform implementation. On Linux/macOS the class will use the internal implementation. When TLS 1.3 is enabled via SSLEnabledProtocols the internal implementation is used on all platforms.

ssl_server_cert_encoded Property

This is the certificate (PEM/Base64 encoded).

Syntax

def get_ssl_server_cert_encoded() -> bytes: ...

ssl_server_cert_encoded = property(get_ssl_server_cert_encoded, None)

Default Value

""

Remarks

This is the certificate (PEM/Base64 encoded). This property is used to assign a specific certificate. The ssl_server_cert_store and ssl_server_cert_subject properties also may be used to specify a certificate.

When ssl_server_cert_encoded is set, a search is initiated in the current ssl_server_cert_store for the private key of the certificate. If the key is found, ssl_server_cert_subject is updated to reflect the full subject of the selected certificate; otherwise, ssl_server_cert_subject is set to an empty string.

This property is read-only.

timeout Property

A timeout for the class.

Syntax

def get_timeout() -> int: ...
def set_timeout(value: int) -> None: ...

timeout = property(get_timeout, set_timeout)

Default Value

60

Remarks

If the timeout property is set to 0, all operations will run uninterrupted until successful completion or an error condition is encountered.

If timeout is set to a positive value, the class will wait for the operation to complete before returning control.

The class will use do_events to enter an efficient wait loop during any potential waiting period, making sure that all system events are processed immediately as they arrive. This ensures that the host application does not "freeze" and remains responsive.

If timeout expires, and the operation is not yet complete, the class fails with an error.

Please note that by default, all timeouts are inactivity timeouts, i.e. the timeout period is extended by timeout seconds when any amount of data is successfully sent or received.

The default value for the timeout property is 60 seconds.

total_charge Property

Represents the total shipment charge.

Syntax

def get_total_charge() -> str: ...

total_charge = property(get_total_charge, None)

Default Value

""

Remarks

This property holds the total charge associated with the shipment. The value is represented in dollars and cents with two decimal places. For instance "1500.25".

This property is read-only.

ups_account_number Property

The shipper's UPS account number.

Syntax

def get_ups_account_number() -> str: ...
def set_ups_account_number(value: str) -> None: ...

ups_account_number = property(get_ups_account_number, set_ups_account_number)

Default Value

""

Remarks

The shipper's UPS account number.

This property describes the shipper's 6- or 10- digit UPS account number.

ups_authorization_token Property

Authorization Token used to authenticate the request.

Syntax

def get_ups_authorization_token() -> str: ...
def set_ups_authorization_token(value: str) -> None: ...

ups_authorization_token = property(get_ups_authorization_token, set_ups_authorization_token)

Default Value

""

Remarks

Authorization Token used to authenticate the request.

This field should be set to the value of a bearer token obtained through OAuth 2.0. For more information on getting a bearer token, see the documentation for the OAuth component.

ups_server Property

URL for the UPS server where the requests are sent.

Syntax

def get_ups_server() -> str: ...
def set_ups_server(value: str) -> None: ...

ups_server = property(get_ups_server, set_ups_server)

Default Value

""

Remarks

URL for the UPS server where the requests are sent. This will overwrite the internal values that the component uses.

Normally, you do not need to set this property. By default, the component will send the request to the preset production end-point. In order to send request to the test environment, you must set the TESTMODE config to true like: component.Config("TESTMODE=true").

The following URLs may be used for testing:

config Method

Sets or retrieves a configuration setting.

Syntax

def config(configuration_string: str) -> str: ...

Remarks

config is a generic method available in every class. It is used to set and retrieve configuration settings for the class.

These settings are similar in functionality to properties, but they are rarely used. In order to avoid "polluting" the property namespace of the class, access to these internal properties is provided through the config method.

To set a configuration setting named PROPERTY, you must call Config("PROPERTY=VALUE"), where VALUE is the value of the setting expressed as a string. For boolean values, use the strings "True", "False", "0", "1", "Yes", or "No" (case does not matter).

To read (query) the value of a configuration setting, you must call Config("PROPERTY"). The value will be returned as a string.

get_rates Method

Returns rate information for a specified or all available UPS RequestedService s.

Syntax

def get_rates() -> None: ...

Remarks

To get the courtesy rate quotes for UPS services, you can call the get_rates method. The requested_service property identifies the UPS service for which you want to retrieve rate information.

reset Method

Resets the internal state of the class and all properties to their default values.

Syntax

def reset() -> None: ...

Remarks

The Reset method does not have any parameters and does not return any value.

on_error Event

Information about errors during data delivery.

Syntax

class UPSFreightRatesErrorEventParams(object):
  @property
  def error_code() -> int: ...

  @property
  def description() -> str: ...

# In class UPSFreightRates:
@property
def on_error() -> Callable[[UPSFreightRatesErrorEventParams], None]: ...
@on_error.setter
def on_error(event_hook: Callable[[UPSFreightRatesErrorEventParams], None]) -> None: ...

Remarks

The on_error event is fired in case of exceptional conditions during message processing.

ErrorCode contains an error code and Description contains a textual description of the error. For a list of valid error codes and their descriptions, please refer to the Error Codes section.

on_notification Event

Notification returned by the server upon successful request (if applicable).

Syntax

class UPSFreightRatesNotificationEventParams(object):
  @property
  def message() -> str: ...

# In class UPSFreightRates:
@property
def on_notification() -> Callable[[UPSFreightRatesNotificationEventParams], None]: ...
@on_notification.setter
def on_notification(event_hook: Callable[[UPSFreightRatesNotificationEventParams], None]) -> None: ...

Remarks

When sending a request, the server may return with a successful reply or an error. However, even when a transaction is successful, a warning or a note might still be returned by the server. In such cases, the on_notification event is fired.

Notifications returned through this event are non-fatal and shipments will still be processes, labels will still be printable, rates are still returned, etc. These notifications should be treated as informational only.

on_ssl_server_authentication Event

Fired after the server presents its certificate to the client.

Syntax

class UPSFreightRatesSSLServerAuthenticationEventParams(object):
  @property
  def cert_encoded() -> bytes: ...

  @property
  def cert_subject() -> str: ...

  @property
  def cert_issuer() -> str: ...

  @property
  def status() -> str: ...

  @property
  def accept() -> bool: ...
  @accept.setter
  def accept(value) -> None: ...

# In class UPSFreightRates:
@property
def on_ssl_server_authentication() -> Callable[[UPSFreightRatesSSLServerAuthenticationEventParams], None]: ...
@on_ssl_server_authentication.setter
def on_ssl_server_authentication(event_hook: Callable[[UPSFreightRatesSSLServerAuthenticationEventParams], None]) -> None: ...

Remarks

During this event, the client can decide whether or not to continue with the connection process. The Accept parameter is a recommendation on whether to continue or close the connection. This is just a suggestion: application software must use its own logic to determine whether or not to continue.

When Accept is False, Status shows why the verification failed (otherwise, Status contains the string OK). If it is decided to continue, you can override and accept the certificate by setting the Accept parameter to True.

on_ssl_status Event

Fired when secure connection progress messages are available.

Syntax

class UPSFreightRatesSSLStatusEventParams(object):
  @property
  def message() -> str: ...

# In class UPSFreightRates:
@property
def on_ssl_status() -> Callable[[UPSFreightRatesSSLStatusEventParams], None]: ...
@on_ssl_status.setter
def on_ssl_status(event_hook: Callable[[UPSFreightRatesSSLStatusEventParams], None]) -> None: ...

Remarks

The event is fired for informational and logging purposes only. This event tracks the progress of the connection.

UPSFreightRates Config Settings

UPSFreightRates Config Settings

HTTP Config Settings

TCPClient Config Settings

SSL Config Settings

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIEKzCCAxOgAwIBAgIRANTET4LIkxdH6P+CFIiHvTowDQYJKoZIhvcNAQELBQAw
...
eWHV5OW1K53o/atv59sOiW5K3crjFhsBOd5Q+cJJnU+SWinPKtANXMht+EDvYY2w
F0I1XhM+pKj7FjDr+XNj
-----END CERTIFICATE-----
\r \n
-----BEGIN CERTIFICATE-----
MIIEFjCCAv6gAwIBAgIQetu1SMxpnENAnnOz1P+PtTANBgkqhkiG9w0BAQUFADBp
..
d8q23djXZbVYiIfE9ebr4g3152BlVCHZ2GyPdjhIuLeH21VbT/dyEHHA
-----END CERTIFICATE-----

Socket Config Settings

Base Config Settings

UPSFreightRates Errors

UPSFreightRates Errors

The class may also return one of the following error codes, which are inherited from other classes.