Module: Usps::Api::Endpoints::RateV4

Included in:
Usps::Api::Endpoints
Defined in:
lib/usps/api/endpoints/rate_v4.rb

Instance Method Summary collapse

Instance Method Details

#rate_v4(options = {}) ⇒ Object

The RateV4 API lets customers calculate the rate for domestic packages and envelopes given the weight and dimensions of the item. The RateV4 API limits the data requested to twenty-five (25) packages per transaction.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • rate_v4_request (required, Hash) —

    API=RateV4 This API returns the current USPS postage corresponding to the parameters given.

    • :revision (String) — Set this value to “2” to return all currently documented response fields. For example: <Revision>2</Revsion>

    • :package (Hash) — See the RateV4 Service Request chart for valid combinations of the following tags.

      • :service (required, <Service>) — [“Description”=>“When <Service> = “ALL”, all eligible retail products will return in the API response.”, “Description”=>“When <Service> = “ONLINE”, all eligible retail and commercial base products will return in the API response.”, “Description”=>“When <Service> = “PLUS”, all eligible retail, commercial base, and commercial plus products will return in the API response.”]

      • :first_class_mail_type (String) — Required when: RateV4Request[Service=‘FIRST CLASS’] or RateV4Request[Service=‘FIRST CLASS COMMERCIAL’], or RateV4Request[Service=’FIRST CLASS HFP COMMERCIAL’] Example: <FirstClassMailType>LETTER</FirstClassMailType> Note: The <FirstClassMailType> tag is returned only if the <ServiceType> submitted is “First Class”. If any other <ServiceType> is returned (Including “First Class Commercial”) the <Container> tag is used. Note: Flats are also known as Large Envelopes

      • :zip_origination (required, String) — ZIP code must be valid. For example: <ZipOrigination>20770</ZipOrigination>

      • :zip_destination (required, String) — ZIP code must be valid. For example: <ZipDestination>54324</ZipDestination>

      • :pounds (required, String) — Value must be numeric. Package weight cannot exceed 70 pounds. For example: <Pounds>2</Pounds> <Pounds>2.12345678</Pounds>

      • :ounces (required, String) — Value must be numeric. Package weight cannot exceed 70 pounds (1120 ounces). For example: <Ounces>0</Ounces> <Ounces>0.12345678</Ounces>

      • :container (required, String) — Use to specify container attributes that may affect postage; otherwise, leave blank. Note: The <FirstClassMailType> tag is used instead of the <Container> tag only if the <ServiceType> submitted is “First Class”. Note: “Cubic Soft Pack” and “Cubic Parcels” are only valid containers for service “Priority Mail Cubic”. Dimensions Length and Height are required when requesting Cubic Soft Pack. Dimensions Length, Height, and Width are required when requesting Cubic Parcels. Note: “VARIABLE” is used to denote that a customer is using packaging other than a USPS-produced Flat Rate Box/Envelope or Regional Rate Box”. Note: <Container> enumerations: “SM FLAT RATE BAG”, “LG FLAT RATE BAG”, “FLAT RATE BOX” only applicable when <Service>=“Connect Local.”

      • :size (String) — Note: This tag has been deprecated. <Size> tag and any values within the <Size> tag will not result in an error response and will not impact rates that are returned.

      • :width (Decimal) — Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For more details on dimensional weight pricing or dimension validation reference DMM pe.usps.com/text/dmm300/index.htm

      • :length (Decimal) — Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For more details on dimensional weight pricing or dimension validation reference DMM pe.usps.com/text/dmm300/index.htm

      • :height (Decimal) — Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For more details on dimensional weight pricing or dimension validation reference DMM pe.usps.com/text/dmm300/index.htm

      • :girth (Decimal) — Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages. For more details on dimensional weight pricing or dimension validation reference DMM pe.usps.com/text/dmm300/index.htm

      • :value (String) — Available when RateV4Request [Revision=‘2’]. Package value. Used to determine availability and cost of extra services. For example: <Value>150.00</Value>

      • :amount_to_collect (String) — Available when RateV4Request [Revision=‘2’]. Collect on delivery amount. Used to determine availability and cost of extra services. For example: <AmountToCollect>150.00</AmountToCollect>

      • :special_services (Hash) — Available when RateV4Request [Revision=‘2’]. Groups the SpecialServices elements. Special Services prices and availability will not be returned when Service = “ALL”, “ONLINE”, or “PLUS”

        • :special_service (Special Service Name) — [Service Name”=>“Insurance”, “ServiceID”=>“100”, Service Name”=>“Insurance – Priority Mail Express”, “ServiceID”=>“101”, Service Name”=>“Return Receipt”, “ServiceID”=>“102”, Service Name”=>“Collect on Delivery”, “ServiceID”=>“103”, Service Name”=>“Certificate of Mailing (Form 3665)”, “ServiceID”=>“104”, Service Name”=>“Certified Mail”, “ServiceID”=>“105”, Service Name”=>“USPS Tracking”, “ServiceID”=>“106”, Service Name”=>“Signature Confirmation”, “ServiceID”=>“108”, Service Name”=>“Registered Mail”, “ServiceID”=>“109”, Service Name”=>“Return Receipt Electronic”, “ServiceID”=>“110”, Service Name”=>“Registered mail COD collection Charge”, “ServiceID”=>“112”, Service Name”=>“Return Receipt – Priority Mail Express”, “ServiceID”=>“118”, Service Name”=>“Adult Signature Required”, “ServiceID”=>“119”, Service Name”=>“Adult Signature Restricted Delivery”, “ServiceID”=>“120”, Service Name”=>“Insurance – Priority Mail”, “ServiceID”=>“125”, Service Name”=>“USPS Tracking Electronic”, “ServiceID”=>“155”, Service Name”=>“Signature Confirmation Electronic”, “ServiceID”=>“156”, Service Name”=>“Certificate of Mailing (Form 3817)”, “ServiceID”=>“160”, Service Name”=>“Certified Mail Restricted Delivery”, “ServiceID”=>“170”, Service Name”=>“Certified Mail Adult Signature Required”, “ServiceID”=>“171”, Service Name”=>“Certified Mail Adult Signature Restricted Delivery”, “ServiceID”=>“172”, Service Name”=>“Signature Confirm. Restrict. Delivery”, “ServiceID”=>“173”, Service Name”=>“Signature Confirmation Electronic Restricted Delivery”, “ServiceID”=>“174”, Service Name”=>“Collect on Delivery Restricted Delivery”, “ServiceID”=>“175”, Service Name”=>“Registered Mail Restricted Delivery”, “ServiceID”=>“176”, Service Name”=>“Insurance Restricted Delivery”, “ServiceID”=>“177”, Service Name”=>“Insurance Restrict. Delivery – Priority Mail”, “ServiceID”=>“179”, Service Name”=>“Insurance Restrict. Delivery – Priority Mail Express”, “ServiceID”=>“178”, Service Name”=>“Insurance Restrict. Delivery (Bulk Only)”, “ServiceID”=>“180”, Service Name”=>“Scan Retention”, “ServiceID”=>“181”, Service Name”=>“Scan + Signature Retention”, “ServiceID”=>“182”, Service Name”=>“Special Handling - Fragile”, “ServiceID”=>“190”, Service Name”=>“USPS Connect Sunday Delivery”, “ServiceID”=>“447”]

        • :content (Group) — Available when RateV4Request. Groups the ContentType and ContentDescription elements.

        • :content_type (String) — Available when RateV4Request [Revision=’2’]. Defines the type of content of the package.

        • :content_description (String) — Available when RateV4Request. Describes the content of the package. Optional but required for ContentType ‘LIVES’.

        • :ground_only (Boolean) — Available when RateV4Request [Revision=’2’]. RateV4Request [Service=’ Retail Ground’] Use “true” when shipment contains mailable hazardous materials, live animals and other “surface-only” items.

        • :sort_by (String) — Available when RateV4Request [Revision=‘2’]. Returns all mailing services available based on item shape. When specified, value in <Container> is ignored. Available when: RateV4Request RateV4Request For example: <SortBy>PACKAGE</SortBy>

        • :machinable (Boolean) — RateV4Request/Machinable is required when: RateV4Request[Service=‘FIRST CLASS’ and (FirstClassMailType=‘LETTER’ or FirstClassMailType=‘FLAT’)] RateV4Request[Service=‘Retail Ground’] RateV4Request RateV4Request If false, First Class Mail Letters and Flats will not be returned. For example: <Machinable>true</Machinable>

        • :return_locations (Boolean) — Include Dropoff Locations in Response if available. Requires “ShipDate” tag.

        • :return_service_info (Boolean) — If a value of “True” is indicated in the request then the response will include the <ServiceInformation> tag containing mail service specific information

        • :drop_off_time (String) — Time Package Will Be Mailed. Enter drop off time in format: HH:mm, such as 13:45. Inclusion of Drop Off Time will result increased accuracy of <CommitmentName> and <CommitmentDate> in the response for Priority Mail and Priority Mail Express variants. For example: <DropOffTime>13:45</DropOffTime>

        • :ship_date (String) — Date Package Will Be Mailed. Ship date may be today plus 0 to 3 days in advance. Enter the date in format: yyyy-mm-dd, such as 2013-07-28. Inclusion of Ship Date will result in <CommitmentName> and <CommitmentDate> in the response for Priority Mail and Priority Mail Express variants For example: <ShipDate Option=“HFP”>2013-07-28</ShipDate>

        • :option (String) — The value of this attribute specifies how the RateV4Response will structure the Priority Express Mail Commitment data elements.

        • :return_dimensional_weight (Boolean) — This tag must be explicitly set to “true” for dimensional weight to be returned in the xml response.

        • :tracking_retention_period (ServiceID) — [“<TrackingRetentionPeriod>”=>““0.5” (6 Months)”, “<TrackingRetentionPeriod>”=>““1” (1 Year)”, “<TrackingRetentionPeriod>”=>““3” (3 Years)”, “<TrackingRetentionPeriod>”=>““5” (5 Years)”, “<TrackingRetentionPeriod>”=>““7” (7 Years)”, “<TrackingRetentionPeriod>”=>““3” (3 Years)”, “<TrackingRetentionPeriod>”=>““5” (5 Years)”, “<TrackingRetentionPeriod>”=>““7” (7 Years)”, “<TrackingRetentionPeriod>”=>““10” (10 Years)”]

        • :sortation_level (Sortation) — [“Description”=>“3-Digit”, “Description”=>“5-Digit”, “Description”=>“Basic”, “Description”=>“Carrier Route”, “Description”=>“Mixed NDC”, “Description”=>“NDC”, “Description”=>“None”, “Description”=>“Presort”, “Description”=>“SCG”, “Description”=>“EMM Tray Box”, “Description”=>“Full Tray Box”, “Description”=>“Half Tray Box”, “Description”=>“Full Tub Tray Box”]

        • :destination_entry_facility_type (Destination Type) — [Type”=>“Destination Delivery Unit”, “Value”=>“DDU”, Type”=>“Destination Network Distribution Unit”, “Value”=>“DNDC”, Type”=>“Destination Sectional Center Facility”, “Value”=>“DSCF”]



48
49
50
51
52
53
54
55
56
 
# File 'lib/usps/api/endpoints/rate_v4.rb', line 48

def rate_v4(options = {})
	throw ArgumentError.new('Required arguments :rate_v4_request missing') if options[:rate_v4_request].nil?

	request = build_request(:rate_v4, options)
	get('https://secure.shippingapis.com/ShippingAPI.dll', {
		API: 'RateV4',
		XML: request,
	})
end