USPS Shipping (RESTful) (USPSr)

spyderrobotics:

Using 1.5.7c and installed the non-encapsulated version. Couple of issues. In the admin panel the module didn't show and it gave an error because it was looking for uspsr.php in the languages>english>modules>shipping folder. The file is actually named lang.uspsr.php. So I just renamed it to uspsr.php and then the module showed up and I was able to configure it. The module works but it also is not grabbing some of the names correctly. For instance when you get a quote it would show MODULE_SHIPPING_USPSR_TEXT_SHORT_TITLE (Ground Advantage) to the user.

I edited line 245 in the module and just changed it to $this->title = 'United States Postal Service';

It does something similar with the name of the module under the admin>module>shipping.

I was able to edit those to get things looking right. Not sure why its not getting the data from the other files. My issue is with the other usps module you could select the weight for each shipping type. For instance I only want up to 1 lb for ground advantage and priority limited to 1 lb or more. Is there a way to put that option back in or any idea where to edit the files to manually put that back in?

lat9:

Right, the USPS/RESTful provides only new-style language files (i.e. lang.uspsr.php); that form of language-file was introduced in zc158.

Yeah as lat9 said, I made this for 1.5.8 onward given that the older style of language files are being phased out. It CAN work with some muscle for 1.5.7, but I would have to rewrite all of the language files to do so.

retched:

Yeah as lat9 said, I made this for 1.5.8 onward given that the older style of language files are being phased out. It CAN work with some muscle for 1.5.7, but I would have to rewrite all of the language files to do so.

You SHOULD be able to use the following gists. Just be sure to put the languages file where necessary and rename them. (the admin.uspsr.php should be copied to /admin/includes/languages/english/extra_definitions/uspsr.php and the catalog.uspsr.php file should be copied to catalog\includes\languages\english\modules\shipping\ . Both should be named to JUST uspsr.php)

https://gist.github.com/retched/bcf66f5c14484d1c0e1e472bc741976a

spyderrobotics:

My issue is with the other usps module you could select the weight for each shipping type

Coming back in a later edit innately (probably the next edit once I fix the quote issue right now). The way I have to pull the JSON file presently is a bit cumbersome but I'm 95% sure it can be done to compare it against a maximum/minimum weight like before.

There is a way to use an observer class (NOTIFY_USPS_UPDATE_OR_DISALLOW_TYPE) to in effect disable a shipping method. But that might be too cumbersome.

retched:

You SHOULD be able to use the following gists. Just be sure to put the languages file where necessary and rename them. (the admin.uspsr.php should be copied to /admin/includes/languages/english/extra_definitions/uspsr.php and the catalog.uspsr.php file should be copied to catalog\includes\languages\english\modules\shipping\ . Both should be named to JUST uspsr.php)

https://gist.github.com/retched/bcf66f5c14484d1c0e1e472bc741976a

Im in a similar situation where I will be stuck in with an older version of ZC until a complete tear down can happen. Which its going to be quite catastrophic since it a 15 year old cart that had been through as much as upgrades as reasonably can. In the light of the USPS api retirement notice, I'm interested to see if this would work reliably in a production environment that really can't be upgraded any further.

Any efforts to provide some reasonable backward compatibility would be greatly appreciated.

chibipaw:

Im in a similar situation where I will be stuck in with an older version of ZC until a complete tear down can happen. Which its going to be quite catastrophic since it a 15 year old cart that had been through as much as upgrades as reasonably can. In the light of the USPS api retirement notice, I'm interested to see if this would work reliably in a production environment that really can't be upgraded any further.

Any efforts to provide some reasonable backward compatibility would be greatly appreciated.

Which version of ZC are you on?

retched:

Which version of ZC are you on?

With munch embarrassment, 1.55f. Because too many active dependencies that are now abandonware, and this is a very active production site.

Wait you mean 1.5.5f right?

Yes, not by choice as mentioned.

FWIW, given my short code review, I believe that this version of USPS could be made usable on Zen Cart versions prior to 1.5.8 and PHP versions prior to 7.3/4 by

• Providing a non-array-based language file, i.e. using the older define-statement method.
• Changing the use of the null-coalesce operator (??) to use the older tertiary operator, e.g.** if (($x ?? 7)) **becomes if (isset($x) ? $x : 7).

If it's at all possible, that is very much appreciated. Im sure not just by me, but buy a lot of people who are kind of stuck in this situation.

chibipaw:

If it's at all possible, that is very much appreciated. Im sure not just by me, but buy a lot of people who are kind of stuck in this situation.

Keep in mind you can continue to use WebTools, the deprecation takes effect in 2026 when USPS plans on turning off WebTools entirely. I'll start setting up for a second side update (most of the logic I don't have to change, luckily) sometime soon but I have a few issues to resolve with the current version first. It's just going to be hard setting up an installation of PHP7 so that I can install ZenCart 1.5.5 and 1.5.7 (for some reason, unless I'm doing something wrong, they REALLY don't want me to install on PHP8).

I'll keep an eye out for any updates, and if you need someone to test it out.
I have disk images on AWS that I can test on without fear of breaking anything on a production box.

This one is a lot! I've tested on Zencart 2.1.0, 1.5.7, and 1.5.5. Turns out it wasn't PHP8's ?? operator that was causing problems, it was the fact that I had a heredoc with extra spaces in its terminating line (which is OK in PHP8, not OK in PHP7) that was causing problems. Still leaving off the coalescence operator on future releases. Additionally, to help with backwards compatibility, there are now define-based language files for the older ZenCart versions. (These won't cause any problems with the newer array-based language files.)

Breaking

• Due to a change in the configuration for the shipping methods, the selection of current shipping methods will be reset with this version. You must now select your shipping methods to use under USPS. (I tried to avoid these kinds of breaking changes but with the way how the selection of the modules is done and the changes to the table holding them, it's unavoidable. This will normally happen if I have to change the way how the USPS identifies its services.)
• Going forward: if you are using encapsulated version v0.0.0, aka the version pulled straight from the GitHub repository "main" branch, the upgrader will fail. You must do a clean install by uninstalling the module from Plugin Manager from your backend and then installing the new version. The development version of v0.0.0 is to be considered an incomplete thought and should NOT be used in active productions. Non-encapsulated versions will still have to do the same until an upgrader is put in place in the module.

Added

• Module now does a brief test to pull a token. If it succeeds, the module remains enabled. But if it fails for any reason whatsoever, the module turns off. This also generates an error message in the Admin area, additionally the module "soft-disables". (The light turns yellow as if you disabled it.)
• Created language define file for Admin side error messages. (Both the admin and client side language files are array-based for ZC 1.5.8+.)
• New flag: MODULE_SHIPPING_USPSR_DIMENSIONAL_CLASS. This will ask if the packages are "Rectangular" or "Nonrectangular". (Are you shipping your orders in cube-like packaging or are you using something like soft poly bags.) This flag only comes into play if you set the packages to be REALLY big or are shipping packages REALLY heavy. The quote will take care of and include any necessary surcharges.
• New flag: MODULE_SHIPPING_USPSR_CUBIC_CLASS. Sets a flag to either "Non-Soft" or "Soft" packaging types for Cubic pricing. (Same question as Dimensional Class but different pricing scheme.)
• Created a toggle to allow the shop to send the full value of the customer's cart as part of the quoting process or to cap it at $5.00. (Some shipping methods in the USPS are limited based on how much value is being sent through it. This especially applies to international shipments as the USPS caps service modes based not only on destination but also the value of the items being sent.) If this toggle is enabled, the insurance calculations will fall short as the value of the insurance is based on how much the calculated cart total is. Use this setting at your peril.
• A flag for the source of the log file has been made. Any log file generated by an admin's action will be precluded with an adm suffix. (Also a warning that each log file is roughly 300KB. Nothing can be done about that as, for diagnostic purposes, I need not just the diagnostic report but also the raw JSONs being sent and received when trying to figure out what went wrong with the module.)
• Created a debug counter for Ground Advantage Cubic, Priority Mail Cubic, and Priority Mail Express Cubic. This helps for deciding on whether to filter the rate for these services further or to just use what is received.
• Expanded the packaging classes into three questions: one pertaining to Media Mail (Machinable/Nonstandard) and Ground Advantage Cubic and Priority Mail Cubic (Rectangular/Nonrectangular and Soft/Non-Soft).
• Expanded definitions and explanations of various configuration settings.
• Added min/max fields from the original USPS module to shipping method selection. These fields allow you to place weight-based clamps on each method. For example: If you entered 1 and 5 in the appropriate boxes (order does not matter, the software will sort it out for you) for USPS Ground Advantage, the module will only offer your customers the USPS Ground Advantage rate if the total package weight (that is items and tare) is within those two settings. NOTE: This does not mean you can offer services that are outside of the USPS limits. (Example: Entering 80 as a maximum does not mean you can offer Ground Advantage to your customers as 70 is the maximum serviceable weight for USPS Ground Advantage.)
• For parity with ZenCart installations older than 2.0.0, there is a file edit that the storeowner should use to define the measurement standard of the site. This is to make sure that everything is dispatched to the USPS in imperial units. If you are using 2.0.0 or newer, do not edit the file at all.
• (REPO HEALTH) Added a new Feature Request YAML form plus created a Pull Request template.

Fixed

• Full compatibility with ZenCart 1.5.7 AND PHP7. (Technically speaking, the code base was compatible with PHP 7.3 and onward, but 7.1 still required Heredocs to end at the first column of the line. There was an extra indent involved with a heredoc and that caused a lot of problems.)
• Added a catch-all to prevent a bugged API response for Media Mail. In short, the values for Nonstandard Basic were being duplicated. USPS is aware of this but there is no telling of when a fix will come. In the interim, the module will filter out the other responses and proceed with just one. This does mean that your Machinable packages will be treated as Nonstandard. (In most cases, the price should still be the same.)
• Filtered off the PMOD (Priority Mail Open and Distribute) responses as well as duplicated domestic Flat Rates.
• Improved filtering from Media Mail, Ground Advantage Cubic, Priority Mail, and Priority Mail Express services. (Fixes issue #13 from the Github.)
• More "industry" terms filtered out. (Open and Distribute methods are filtered out.)
• Changed USPS Ground Advantage to just read Ground Advantage instead.
• Fixed validation of zipcodes: The module now tries to see if the order has a US destination. If so, disable the module if someone enters something that isn't a 5 or 9-digit zip code.

Changed

• Error messages in the admin backend now use $messageStack instead of attaching it to the row of details.
• Improved README to give directions on how to create API credentials. (Wiki was also created and articles were created there.)
• The internal handling of some of the shipping methods has changed. (Namely USPS Ground Advantage, Priority Mail, Media, and Priority Mail Express. Each of these has a weird naming scheme in the API that was either causing rates to not appear or appear more than once in a non-descriptive way. Also, see issue #13 and various comments on the repository.)
• Changed machinability flag to only apply with Media Mail. The USPS API will automatically determine if a package would be machinable or nonstandard, the term irregular has been retired for other services. However, for Media Mail, the seller will need to provide a bit of detail.
• Renamed MODULE_SHIPPING_USPSR_PROCESSING_CLASS to MODULE_SHIPPING_USPSR_MEDIA_CLASS. This is an internal change. Makes it easier to identify in the code.
• Sanitized the debug logs by hiding the "client secret" from the JSON file that is saved in the log. (It's still dispatched but seeing the secret is not necessary.)

Removed

• Deleted old versions from repository files. The old versions will live in the releases section of the GitHub and ZenCart Release. (This makes it easier to version track.) Going forward, the main directory of the module on the repository will be renamed to 0.0.0 and then each release will have a separate branch with any necessary changes. The "tags" will be based on that targeted branch.

Download will be available once approved in ZenCart Module DB. Can also visit the repository and grab the latest release from the links on the side.

If there are any problems or questions, please raise them here.

Noting that the download has been approved: https://www.zen-cart.com/downloads.php?do=file&id=2395

Wow! 'Nuff said.

Minor Update submitted for approval. Changes are listed below:

Added

• The module will now call into the ZenCart Plugin database to see if a new version is available. If there is, you will see a banner on the top of the page alerting you. #19
• Ground Advantage and Ground Advantage Cubic will now be squashed into the cheaper method being offered. Same with Priority Mail and Priority Mail Cubic. #23. (In short, if you have both Priority Mail and Priority Mail Cubic quoted, with the toggle made for Priority Mail, the module will choose the cheaper of the two methods and display that.)

Removed

• Removed the check and comparison to see what format the site is using for shipping and length measurements on upgrades. (It was supposed to check if kilograms was the rate at the time of installation and then convert the defaults to that. Now, the module will check on install, place those defaults, and leave it. This means if you change the measuring standard, you'll have to reset the limits of the shipping methods.)
• Removed the unit of measure from the shipping methods table.

Changed

• Debug mode now has two separate modes: Display Errors, and Generate Logs. If errors are found, they are hidden from the customer view unless toggled on. Additionally, you can generate logs for all requests. (TODO: On any error, generate a log regardless of setting.)

Fixed

• There was a spelling error for "Priority Mail" which made "Priorty Mail". That was fixed.
• Resolved #25: Some error messages still bled through even though there was a series of flags and checks to make sure not to bother with launching the quote. Now the logic is: If the order country is bound to the United States and there is no zip code, the module will not try to get a quote. If the quote is requested for an order going elsewhere, the Zip Code is less important.

The ZenCart Module will now have both the regular and encapsulated files listed in one singular entry. Additionally, all version are drag and drop. (Meaning if you installed the regular version of 1.0.0 or earlier, you can just replace the files with the files from the newer version with very little incident.)

Also should be noted that the version numbering SHOULD be fixed. (I was submitting them without the v attached which caused confusing messages in ZenCart if you used the Encapsulated version. Going forward I'll be sure to add it in.)

How do I get the API keys?

Read the documentation.

https://github.com/retched/ZC-USPSRestful/wiki/Getting%20Started#installing

I turned restful off so no debug files from it.

ZC 2.1.0 and all below are latest
Bootstrap
EO 5
OPC
POSM

Received the following on first run of encapsulated files from current GitHub

[03-Mar-2025 18:01:29 UTC] PHP Fatal error: Uncaught TypeError: Cannot access offset of type string on string in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php:916
Stack trace:
#0 /includes/classes/shipping.php(257): uspsr->quote('')
#1 /includes/modules/pages/checkout_one/header_php.php(220): shipping->quote()
#2 /index.php(35): require('/home/enigjohn/...')
#3 {main}
thrown in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php on line 916

[03-Mar-2025 18:01:29 UTC] Request URI: /index.php?main_page=checkout_one, IP address: 216.177.186.199
--> PHP Fatal error: Uncaught TypeError: Cannot access offset of type string on string in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php:916
Stack trace:
#0 /includes/classes/shipping.php(257): uspsr->quote('')
#1 /includes/modules/pages/checkout_one/header_php.php(220): shipping->quote()
#2 /index.php(35): require('/home/enigjohn/...')
#3 {main}
thrown in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php on line 916.

[03-Mar-2025 18:01:29 UTC] Request URI: /index.php?main_page=checkout_one, IP address: 216.177.186.199
--> PHP Fatal error: Uncaught TypeError: Cannot access offset of type string on string in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php:916
Stack trace:
#0 /includes/classes/shipping.php(257): uspsr->quote('')
#1 /includes/modules/pages/checkout_one/header_php.php(220): shipping->quote()
#2 /index.php(35): require('/home/enigjohn/...')
#3 {main}
thrown in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php on line 916.

dbltoe:

I turned restful off so no debug files from it.

ZC 2.1.0 and all below are latest
Bootstrap
EO 5
OPC
POSM

Received the following on first run of encapsulated files from current GitHub

[03-Mar-2025 18:01:29 UTC] PHP Fatal error: Uncaught TypeError: Cannot access offset of type string on string in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php:916
Stack trace:
#0 /includes/classes/shipping.php(257): uspsr->quote('')
#1 /includes/modules/pages/checkout_one/header_php.php(220): shipping->quote()
#2 /index.php(35): require('/home/enigjohn/...')
#3 {main}
thrown in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php on line 916

[03-Mar-2025 18:01:29 UTC] Request URI: /index.php?main_page=checkout_one, IP address: 216.177.186.199
--> PHP Fatal error: Uncaught TypeError: Cannot access offset of type string on string in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php:916
Stack trace:
#0 /includes/classes/shipping.php(257): uspsr->quote('')
#1 /includes/modules/pages/checkout_one/header_php.php(220): shipping->quote()
#2 /index.php(35): require('/home/enigjohn/...')
#3 {main}
thrown in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php on line 916.

[03-Mar-2025 18:01:29 UTC] Request URI: /index.php?main_page=checkout_one, IP address: 216.177.186.199
--> PHP Fatal error: Uncaught TypeError: Cannot access offset of type string on string in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php:916
Stack trace:
#0 /includes/classes/shipping.php(257): uspsr->quote('')
#1 /includes/modules/pages/checkout_one/header_php.php(220): shipping->quote()
#2 /index.php(35): require('/home/enigjohn/...')
#3 {main}
thrown in /zc_plugins/USPSRestful/v0.0.0/catalog/includes/modules/shipping/uspsr.php on line 916.

Oh wait, you said you pulled from current.

Edit Orders shouldn't affect it nor should Bootstrap (I actually use Bootstrap myself.)

I have to see what's going on with One Page Checkout.

So far I can't replicate this, even with Edit Orders. I have each of the above modules installed. Can you let me know of any other details that you would think could replicate this?