Module: Usps::Api::Endpoints::USPSReturnsLabel

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

Instance Method Summary collapse

Instance Method Details

#usps_returns_label(options = {}) ⇒ Object

The Web Tools USPS Returns Label API enables customers to receive USPS Returns service labels which are processed using the new automated returns process via Package Platform. USPS Returns service account holders will pay postage and fees through an Enterprise Payment System (EPS) account so that items can be returned by their customers (at no charge to their customers) using merchant provided USPS Returns service labels. The API allows integrators to request USPS Returns service labels for items that can be mailed using First-Class Package Return Service, Priority Mail Return Service, and Ground Return Service. For additional USPS Returns service details, reference: www.federalregister.gov/documents/2020/02/25/2020-03170/usps-returns-service.

Parameters:

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

Options Hash (options):

  • usps_returns_label_request (required, Hash) —

    Used with API=USPSReturnsLabel

    • :option (String) — For future use.

    • :revision (String) — For future use. Used to indicate API version.

    • :image_parameters (required, Hash) — Group containing all request parameters pertaining to the Label Image generation.

      • :image_type (required, String) — Label Image Type. See Appendix A for Image parameter options. For example: <ImageType>PDF</ImageType>

      • :image_parameter (String) — Returns alternate label image. See Appendix A for Image parameter options. For example: <ImageParameter>4X6LABEL</ImageParameter>

      • :customer_first_name (String) — First Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Note: <CustomerFirstName> and <CustomerLastName> values have a combined 32-character limit when printed on label. Combined values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.

      • :customer_last_name (String) — Last Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Note: <CustomerFirstName> and <CustomerLastName> values have a combined 32-character limit when printed on label. Combined values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.

      • :customer_firm (String) — Firm Name of customer returning package. Printed on label and receipt. Either <CustomerFirstName> and <CustomerLastName> OR <CustomerFirm> required. Minimum of 1 character required. Note: <CustomerFirm> has a 32-character limit when printed on label. Values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.

      • :customer_address1 (String) — Secondary address unit designator and number (such as an apartment or suite number). For example: “APT 202” or “STE 100” etc. Note: This tag must be included in the request, even if the value is null, to return a successful response. For addresses that do not require secondary information, integrators should include “<CustomerAddress1/>” in the request.

      • :customer_address2 (required, String) — Address of customer returning the package. (Primary Street address). For example: <CustomerAddress2>123 Main St.</CustomerAddress2>

      • :customer_urbanization (String) — Urbanization of customer returning the package.

      • :customer_city (required, String) — City of customer returning the package.

      • :customer_state (required, String) — State of customer returning the package. Value should be passed as two-letter state abbreviation. For example: <CustomerState>DC</CustomerState>

      • :customer_zip5 (required, String) — ZIP Code of customer returning the package.

      • :customer_zip4 (String) — ZIP+4 Code of customer returning the package.

      • :po_zip_code (String) — ZIP Code of Post Office or collection box where item is mailed. May be different than CustomerZip5. This tag will take precedence over CustomerZip5 when provided. For example: <POZipCode>20770</ POZipCode>

      • :allow_non_cleansed_origin_addr (Boolean) — Allows Non-Validated Origin Street Address. Enter “true” to bypass street address validation failures/errors or “false” if only validated addresses should be allowed. Note: Integrators are recommended to always use “false” to ensure no delivery issues. In the event USPS cannot validate the street address, this tag will “bypass” address validation error when “true” is indicated to allow label creation which could impact delivery. The <AllowNonCleansedOriginAddr> excludes City, State, and ZIP Code which must be valid for a successful response. Reference pe.usps.com/text/pub28/28c2_001.htm.

      • :retailer_attn (String) — Attention line for Retailer Address. If supplied, this optional value will override the value stored in the Retailers WebTools Profile. Note: <RetailerATTN> has a 32-character limit when printed on label. Values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.

      • :retailer_firm (String) — Firm Name of Retailer Address for return package. Printed on label and receipt. <RetailerFirm> is required for Efulfillment customers using <ReturnsPostageType> = 5. Minimum of 1 character required. Note: <CustomerFirm> has a 32-character limit when printed on label. Values exceeding 32 characters will be truncated due to space limitations on the label. API request eligible to accept up to 50 characters.

      • :retailer_address1 (String) — Secondary address unit designator and number (such as an apartment or suite number). For example: “APT 202” or “STE 100” etc. Note: <RetailerAddress1> may be specified by Efulfillment customers using <ReturnsPostageType> = 5. The value supplied will override the value stored in the Retailers WebTools Profile. Efulfillment customers supplying an empty tag or not supplying this tag will also override the value stored in the Retailers WebTools Profile resulting in no RetailerAddress1 line being displayed.

      • :retailer_address2 (String) — Address of Retailer where the package will be returned. (Primary Street address). For example: <RetailerAddress2>123 Main St.</ RetailerAddress2> Note: <RetailerAddress2> is required for Efulfillment customers using <ReturnsPostageType> = 5. Minimum of 1 character required.

      • :retailer_city (String) — City of Retailer where the package will be returned. Note: <RetailerCity> is required for Efulfillment customers using <ReturnsPostageType> = 5.

      • :retailer_state (String) — State of Retailer where the package will be returned. Value should be passed as two-letter state abbreviation. For example: <RetailerState >DC</ RetailerState > Note: <RetailerState> is required for Efulfillment customers using <ReturnsPostageType> = 5.

      • :retailer_zip5 (String) — ZIP Code of Retailer where the package will be returned. Note: <RetailerZip5> is required for Efulfillment customers using <ReturnsPostageType> = 5.

      • :retailer_zip4 (String) — ZIP+4 Code of Retailer where the package will be returned. Note: <RetailerZip4> is required for Efulfillment customers using <ReturnsPostageType> = 5.

      • :retailer_email (String) — Email for Retailer of the return package. Note: Either <RetailerEmail> OR <RetailerPhone> is required for Efulfillment customers using <ReturnsPostageType> = 5.

      • :retailer_phone (String) — Phone number for Retailer of the return package. Note: Either <RetailerEmail> OR <RetailerPhone> is required for Efulfillment customers using <ReturnsPostageType> = 5.

      • :weight_in_ounces (Integer) — Package weight used to calculate postage. Items must weigh 70 pounds (1120 ounces) or less. For example: <WeightInOunces>80</ WeightInOunces> Note: If weight not supplied, 4oz used.

      • :service_type (required, String) — Enter one of the valid Mail Service entries: “PRIORITY” for Priority Mail Return Service. “FIRST CLASS” for First-Class Package Return Service. “GROUND” for Ground Return Service.

      • :returns_postage_type (String) — The Postage Type for the Returns Label. Note: Required for USPSReturns callers registered as Efulfillment users. Non-Efulfillment users may omit this tag or supply it with an empty value.

      • :width (Decimal) — Value must be numeric. Units are inches. For example: <Width>5.5</ Width> Note: 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 details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. pe.usps.com/text/dmm300/index.htm

      • :length (Decimal) — Value must be numeric. Units are inches. Length should be longest dimension when compared to Width and Height values supplied. For example: <Length>11</Length> Note: 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 details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. pe.usps.com/text/dmm300/index.htm

      • :height (Decimal) — Value must be numeric. Units are inches. For example: <Height>7</Height> Note: 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 details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail. pe.usps.com/text/dmm300/index.htm

      • :girth (Decimal) — Note: Girth is required only for a non-rectangular package. For rectangular packages, girth must be left blank. Value must be numeric. Units are inches. Girth is distance around the thickest part of package (perpendicular to the length). For details on dimensional weight pricing, please reference the Domestic Mail Manual Section 123.1.4 for Retail Mail and Section 223.1.6 for Commercial Mail pe.usps.com/text/dmm300/index.htm. For example: <Girth>25</Girth> Note: If partial dimensions are provided, an error response will return. (i.e. Length, Width, and Height must all be supplied with Girth).

      • :machinable (Boolean) — Indicates if packaging is Machinable. Used to calculate postage. For example: <Machinable>true</Machinable>

      • :vendor_code (String) —

      • :vendor_product_version_number (String) —

      • :mail_owner_mid (String) —

      • :customer_ref_no (String) — Used to collect RMA number.

      • :print_customer_ref_no (Boolean) — Indicated if the <CustomerRefNo> data should be displayed on the label. For example: <Machinable>true</Machinable>

      • :customer_ref_no2 (String) — Used to collect merchant ID. Note: <CustomerRefNo2> is required for Efulfillment customers using <ReturnsPostageType> = 5.

      • :print_customer_ref_no2 (Boolean) — Indicated if the <CustomerRefNo2> data should be displayed on the label. For example: <Machinable>true</Machinable>

      • :sender_name (String) — Used for the USPS Tracking email. Indicates the name of the person or company sending the USPS tracking email notification. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.

      • :sender_email (String) — Used for the USPS Tracking email. Indicates the email address of sender used for USPS tracking email notification. Valid email addresses must be used. Note: <RecipientEmail> must be populated to generate USPS tracking email notification. If <SenderEmail> provided without <RecipientEmail>, USPS tracking email notification will not be generated. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.

      • :recipient_name (String) — Used for the USPS Tracking email. Indicates the name of the person or company receiving the USPS tracking email notification. If recipient name not provided, email will be addressed to <RecipientEmail> value provided. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.

      • :recipient_email (String) — Required to generate the USPS Tracking email. Indicates email address of recipient receiving the USPS tracking email notification. Valid email addresses must be used. Note: No email is returned when generating a Sample (i.e. API=USPSReturnsLabelCertify) request.

      • :tracking_email_pdf (Boolean) — Used to indicate if a PDF returns label will be attached (true) or not (false) to the USPS Tracking email.

      • :extra_services (Hash) — Groups extra services elements

        • :extra_service (Service Name) — [Name”=>“Insurance (Non-Priority)”, “Service ID”=>“100”, Name”=>“Insurance (Priority)”, “Service ID”=>“125”, Name”=>“Signature Confirmation Electronic”, “Service ID”=>“156”]

        • :insured_amount (Decimal) — Use this tag for entering an insurance amount, if applicable. For example: <InsuredAmount>100.00</InsuredAmount> Note: The maximum insurance available may vary by the Returns Mail Service type requested.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/usps/api/endpoints/usps_returns_label.rb', line 70

def usps_returns_label(options = {})
	throw ArgumentError.new('Required arguments :usps_returns_label_request missing') if options[:usps_returns_label_request].nil?
	throw ArgumentError.new('Required arguments :usps_returns_label_request, :image_parameters missing') if options[:usps_returns_label_request][:image_parameters].nil?
	throw ArgumentError.new('Required arguments :usps_returns_label_request, :image_parameters, :image_type missing') if options[:usps_returns_label_request][:image_parameters][:image_type].nil?
	throw ArgumentError.new('Required arguments :usps_returns_label_request, :image_parameters, :customer_address2 missing') if options[:usps_returns_label_request][:image_parameters][:customer_address2].nil?
	throw ArgumentError.new('Required arguments :usps_returns_label_request, :image_parameters, :customer_city missing') if options[:usps_returns_label_request][:image_parameters][:customer_city].nil?
	throw ArgumentError.new('Required arguments :usps_returns_label_request, :image_parameters, :customer_state missing') if options[:usps_returns_label_request][:image_parameters][:customer_state].nil?
	throw ArgumentError.new('Required arguments :usps_returns_label_request, :image_parameters, :customer_zip5 missing') if options[:usps_returns_label_request][:image_parameters][:customer_zip5].nil?
	throw ArgumentError.new('Required arguments :usps_returns_label_request, :image_parameters, :service_type missing') if options[:usps_returns_label_request][:image_parameters][:service_type].nil?

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