Configuring Shipping by Weight: Rate Tiers, Bulk CSV Management and Checkout Messages
Summary
The Shipping by weight delivery computation method varies delivery cost — and which delivery methods a customer can choose — according to the total weight of their order. This guide covers the capability end to end: enabling the method, building your rate tier table, narrowing tiers by state or province and by postcode pattern, controlling which tier wins when several match, managing the whole table in bulk with CSV export and import, restricting checkout to your configured methods, telling customers when an order's weight falls outside every tier, and troubleshooting rates with Debug mode.
Problem
Weight-based shipping lets you charge more to ship a heavy order, and restrict heavy orders to the delivery methods that can actually carry them. Before July 2026 a rate tier could only be matched on country and weight band, and tiers had to be added one row at a time using a form beneath the tier table. There was no way to differentiate rates within a country by state, province or postcode; no bulk way to build or maintain a large rate table; and no way to tell a customer why no delivery option appeared when their order's weight fell outside every configured tier. R26-31 addresses all three and redesigns the configuration page in the process, so this article documents the current page in full and supersedes the earlier Shipping by Weight walkthrough, which described the previous layout.
Environment
Applies to any storefront using the Shipping by weight delivery computation method. Weights are entered in the storefront's primary weight unit, which the tier dialog shows in its field labels (kg(s) on a default configuration). Location-based matching is enabled by default.
Configuration
Step 1: Enable the Shipping by weight method
In the admin, go to Configuration > Delivery > Delivery Computation (Shipping for US customers). Find Shipping by weight in the list of delivery rate computation methods, click Edit on that row, tick the checkbox in the Is active column, then click Update. Once the method is active, its rates appear at checkout whenever an order qualifies for one of the tiers you configure below.
Step 2: Open the Shipping by weight configuration page
Still on the Delivery Computation list, click Configure on the Shipping by weight row. The page has three parts, from the top: Import and export for bulk work, the rate tier table that drives the whole method, and Settings for the page-level options.
Step 3: Understand the rate tier table
Shipping by weight is driven entirely by the rows in this table. Each row is one rate tier — a combination of location, delivery method and weight range, together with the charge to apply when an order matches it. The columns are Country, State / Province, Delivery method, Weight from, Weight to, Use percentage, Charge %, Charge amount, Postcode regex and Execution order, plus Actions for editing a row. Use Search above the table to filter a large rate table, and the per-row checkboxes with Delete selected to remove several tiers in one go.
Step 4: Add a rate tier
Click Add tier to open the Add a new tier dialog, then fill in the fields:
-
Country — the country the tier applies to, so you can set completely different tiers per country. Leave it as * to make the tier apply to all countries.
-
State / Province — narrows the tier to one state or province within the chosen country. The list is filtered by the country you pick; leave it as * (any state) to cover the whole country.
-
Delivery method — the method the customer sees at checkout when they match this tier. The list is populated from Configuration > Delivery > Delivery Methods.
-
Weight from / Weight to — the weight range an order's total weight must fall inside to qualify for this tier. The labels show the storefront's weight unit, for example Weight from (kg(s)).
-
Use percentage — tick Calculate charge as percentage to charge a percentage of the order subtotal instead of a flat rate.
-
Charge % — the percentage of the subtotal to charge, used when Use percentage is ticked.
-
Charge amount — the flat delivery charge in the store currency, used when Use percentage is not ticked.
-
Postcode regex — an optional regular expression the delivery postcode must match, for example ^[A-Z]{1,2}\d{0,9}$.
-
Execution order — breaks ties when more than one tier matches equally well; the tier with the lower execution order wins.
Click Save to add the tier. A tier that leaves State / Province as any state and Postcode regex empty acts as the catch-all for its country.
Step 5: Narrow a tier to a state or province
Choose the country first, then pick the State / Province — the list only offers states belonging to that country. A tier with a state set is more specific than a country-only tier, so it is preferred when both match the delivery address.
Step 6: Narrow a tier to a postcode pattern
Set Postcode regex to a regular expression matching the postcodes the tier should cover. This is the most specific match available, so a postcode tier wins over a state tier, which in turn wins over a country-only tier.
Step 7: Break ties with Execution order
When two tiers are equally specific and both match an order, Execution order decides which one is used — the tier with the lower execution order wins. Leave it at 0 unless you have overlapping tiers you need to prioritise deliberately.
Step 8: A worked example — three weight tiers
A simple all-countries setup with three tiers: First Class for orders under 10kg at a flat £8; Second Class - Light for 10kg up to 20kg at a flat £5; and Second Class - Heavy for 20kg and above at 15% of the subtotal (Use percentage ticked, Charge % set to 15). Enter these as Weight from 0 / Weight to 9.9999, then 10 / 19.9999, then 20 / 10000000000.
Two things to get right in any tier set:
-
Ranges must not overlap. Leave a small gap — end one tier at 9.9999 and start the next at 10, rather than ending one and starting the next both at 10 — so an order can only ever qualify for one tier per delivery method.
-
Cover the full range of order weights you could receive. Start your lowest tier at 0 and give your highest tier a ceiling no real order will exceed. An order whose weight falls outside every tier gets no delivery option from this method at all, which is what the weight messages in Step 13 are for.
Step 9: Edit, search and bulk-delete tiers
Use Edit in a row's Actions column to reopen that tier in the same dialog. For a large table, Search above the table filters the rows down. To remove several tiers at once, tick their row checkboxes and click Delete selected — the button stays disabled until at least one row is ticked.
Step 10: Export the whole rate table as a CSV
Under Import and export, click Download CSV to export every tier currently configured. This is the fastest way to review a large table, hand it to someone else to edit, or keep a copy of the current rates before making sweeping changes.
Step 11: Import a rate table from a CSV
Click Download sample template to get a correctly formatted file (useful when the table is empty and you are building it from scratch). Fill it in, choose the file, then click Upload and import. Validation is all-or-nothing: if any row has a problem, such as a duplicate tier or an unrecognised delivery method, nothing is saved and the errors are listed so you can fix the file and try again. Imports of up to 10,000 rows run as a background job, with a notification when they finish and an entry in the activity log.
Step 12: Restrict checkout to your configured methods
Under Settings, tick Limit delivery options to configured ones if the only delivery methods offered at checkout should be the ones configured in this table. Leave it unticked to let your other active delivery computation methods contribute their own options alongside these.
Step 13: Tell customers when an order's weight falls outside every tier
Under Settings, set Maximum weight message and Minimum weight message. These are shown at checkout when an order's total weight is above the highest, or below the lowest, weight configured across your tiers — the situation that previously left the customer with no delivery option and no explanation. Both are empty by default, which shows no message. Click Save when you are done.
Step 14: Troubleshoot a rate with Debug mode
Debug mode shows the plugin's detailed tier-matching reasoning on the checkout page, which is the quickest way to understand why a particular rate was chosen or why none appeared. This reasoning is visible to customers, so turn it on only while investigating a rate problem and turn it off again afterwards.
Verification
Enable the method and add a country-only catch-all tier, then place a test order inside its weight range and confirm the expected delivery method and charge appear at checkout. Add a State / Province or Postcode regex value to a second tier and place a test order matching it, confirming the more specific tier is used ahead of the country-only catch-all. Export the tier table, make a change, and re-import it, confirming the change is reflected once the import completes. Temporarily set a Maximum or Minimum weight message and place an order outside every tier's range to confirm the message appears at checkout, then clear it once done. If a rate ever looks wrong, turn on Debug mode, reproduce the order, and read the reasoning shown on the shipping method card before turning debug mode back off.
Closing note
Existing country-only tiers are unaffected and continue to work exactly as before — State / Province, Postcode regex and Execution order are entirely optional, and a tier that leaves them unset behaves exactly as it always has.