ARTICLE

Magento 2 Table Rate Shipping: CSV Import, Weight and Destination Rules, and Custom Carrier Fallbacks on Adobe Commerce

warehouse worker scanning packages near a conveyor belt in a modern fulfillment center with natural light

Magento 2 table rate shipping lets you define shipping costs based on combinations of destination, order weight, subtotal, or item count through a CSV file uploaded in the admin panel. It replaces flat rate guesswork with granular rules that match how carriers actually price shipments across zones and thresholds.

How Table Rate Shipping Works in Magento 2

Table rate shipping is a built-in Adobe Commerce feature that calculates shipping costs by matching checkout data against rows in an imported CSV file. When a customer enters their shipping address, Magento looks up the destination (country, region, zip code) and the order’s weight, subtotal, or item count, finds the matching row, and returns the price from that row as the shipping rate.

The system supports three condition types that determine which order attribute drives the rate lookup:

Condition Type Rate Based On Best For
Weight vs. Destination Total order weight in the configured unit Physical goods with weight-based carrier contracts
Price vs. Destination Order subtotal before tax and discounts Tiered free shipping thresholds or value-based rates
Number of Items vs. Destination Total quantity of items in the cart Per-item surcharges or flat rates per piece

You pick one condition type per website. All rows in your CSV must follow that condition’s column structure. You cannot mix weight-based and price-based rules in the same import file.

Virtual products (downloadable items, gift cards) have no weight, so they do not affect weight-based calculations. They do count toward subtotal and item count conditions, which can matter when your store sells a mix of physical and digital products.

The CSV File Format

The CSV has five columns. The exact headers depend on your chosen condition, but the structure is always the same:

For Weight vs. Destination:

Country Region/State Zip/Postal Code Weight (and above) Shipping Price
USA California 90210 0 5.99
USA California 90210 10 12.99
USA * * 0 8.99

For Price vs. Destination, the fourth column becomes “Order Subtotal (and above)” instead of “Weight (and above).” For Number of Items, it becomes the item count threshold.

The “and above” part is critical. A row with “Weight (and above)” set to 10 means that rate applies to orders weighing 10 units or more, up until the next weight threshold. If you have rows at 0, 10, and 25, an order weighing 15 units matches the row at 10. This is a floor-based lookup, not an exact match.

Column Rules

Country must be a three-character ISO 3166-1 alpha-3 code (USA, CAN, GBR, DEU). Using two-letter codes like US or CA will cause the import to fail silently or match nothing at checkout.

Region/State must match the region name exactly as configured in your Magento store under Stores > Configuration > General. Case matters. “California” works; “california” or “CA” might not, depending on how regions are stored in your installation. When you export the existing table rates CSV, the region names in that export are the values Magento expects.

Zip/Postal Code accepts a single code or an asterisk. Magento’s native table rates do not support zip ranges (like 90000-90999). If you need range-based zip matching, you need a third-party extension or a custom shipping carrier module.

Weight values support up to four decimal places. The shipping price is in the store’s base currency.

Wildcard Rows and Sort Order

An asterisk () in any destination column matches all values for that field. A row with Country “USA,” Region “,” and Zip “*” catches every US address that did not match a more specific row.

Row order determines priority. Place specific rows first and wildcard rows last. When Magento evaluates the table, it scans from top to bottom and uses the first match where the destination and condition value fit. If a wildcard row appears before a specific one, the specific row never gets reached.

A practical pattern for US shipping:

Country Region/State Zip/Postal Code Weight (and above) Shipping Price
USA Alaska * 0 15.99
USA Alaska * 20 29.99
USA Hawaii * 0 15.99
USA Hawaii * 20 29.99
USA * * 0 7.99
USA * * 20 14.99
CAN * * 0 19.99
* * * 0 39.99

This covers Alaska and Hawaii at higher rates, the rest of the US at standard rates, Canada at its own rate, and everything else at an international rate. Each destination has two weight tiers.

Setting Up Table Rate Shipping Step by Step

  1. Go to Stores > Configuration > Sales > Delivery Methods > Table Rates.
  2. Switch the configuration scope to your website (not Default Config or Store View). The export and import controls only appear at the website scope level.
  3. Set Enabled to Yes. Enter a Title (what the customer sees as the carrier name, like “Standard Shipping”) and a Method Name (the specific method, like “Ground”).
  4. Choose your Condition from the dropdown.
  5. Optionally configure “Include Virtual Products in Price Calculation” if you sell digital goods and want them counted.
  6. Set the Handling Fee type (fixed or percent) and amount if you want to add a markup on top of the CSV rates.
  7. Click Export CSV. This gives you a template file with the correct headers for your chosen condition.
  8. Fill in the rows following the format above. Save as UTF-8 encoded CSV.
  9. Back in the admin, click Browse next to Import, select your file, and click Save Config.
  10. Flush the configuration cache (System > Cache Management).
  11. Test at checkout with addresses that should match different rows to verify the rates.

If the import fails, start by checking region names against the exported template. The most common failure is a region name that does not match the store’s configured region list.

When Table Rates Are Not Enough

Table rates work well for straightforward zone-and-weight pricing, but they hit limits when your shipping logic gets more complex:

  • No zip code ranges. You cannot specify 90000-90999 as a range. Each zip code is either exact or wildcard.
  • Single condition per website. You cannot combine weight and subtotal rules in one table.
  • No multi-carrier support. Table rates are one carrier with one method. You cannot offer “Ground” and “Express” with different rate tables from the same table rate configuration.
  • No real-time rate calculation. The rates are static values in a CSV. If your carrier pricing changes weekly, you need to re-import every time.
  • No dimensional weight. The weight condition uses actual weight only. If your carrier prices by dimensional weight, table rates cannot handle that.

When you hit these limits, you have two options: a third-party table rate extension with more columns and conditions, or a custom shipping carrier module.

Building a Custom Carrier Module as a Fallback

When table rates cannot express your pricing logic, a custom carrier module gives you full control. The carrier plugs into Magento’s checkout the same way table rates do, but your PHP code calculates the rate instead of a CSV lookup.

The module lives at app/code/Vendor/CustomShipping/ and needs five files:

registration.php registers the module with Magento’s component system.

etc/module.xml declares the module name.

etc/config.xml sets default configuration values: whether the carrier is active, its title, method name, default shipping cost, and the fully qualified class name of your carrier model.

etc/adminhtml/system.xml adds the carrier’s configuration fields to the admin panel under Stores > Configuration > Sales > Delivery Methods.

Model/Carrier/Customshipping.php is where the actual rate logic lives. This class extends AbstractCarrier and implements CarrierInterface. The critical method is collectRates:

The collectRates method receives a RateRequest object containing the destination address, cart items, and totals. Your code examines this data, calculates the shipping cost, creates a Method result with the price, and returns it. If the carrier should not be available for this request (wrong country, too heavy, excluded product type), it returns false and Magento skips it.

This is the same extension pattern used for REST API endpoints and GraphQL resolvers on Adobe Commerce. If your team has built any Magento module before, the structure will be familiar.

For merchants on Adobe Commerce as a Cloud Service, consider using the out-of-process shipping carrier OOPE module instead of an in-process PHP carrier. It lets you register an external service as a shipping carrier through webhooks, keeping your rate calculation logic outside the Commerce codebase entirely.

Table Rates on a Hyva Storefront

Table rate shipping works on Hyva without any frontend modification. The rates are calculated server-side and returned through the same GraphQL shipping method queries that Hyva’s Alpine.js checkout components already consume. When a customer enters their address, the available_shipping_methods query returns table rate results alongside any other active carriers.

Custom carrier modules also work on Hyva as long as they follow the standard CarrierInterface contract. Hyva’s checkout does not render carrier-specific frontend templates the way Luma does, so if your custom carrier needs to display extra UI (insurance options, delivery time windows), you will need to build that as an Alpine.js component that talks to a custom GraphQL endpoint rather than a knockout.js template.

Troubleshooting CSV Import Failures

The most common table rate problems and how to fix them:

“Please correct Region/State” error on import. The region name in your CSV does not match what Magento expects. Export the existing table rates first and use the region names from that export. If you are selling to countries where Magento does not have regions configured by default (many countries outside the US, EU, and Canada), you need to add those regions in the admin or use a wildcard.

Import succeeds but rates do not appear at checkout. Check that the configuration scope is set to the correct website, not Default Config. Also confirm that your condition type matches your CSV columns. If you chose “Weight vs. Destination” but your CSV has subtotal thresholds, nothing will match.

“Invalid File Format” on upload. This usually means the CSV delimiter or encoding is wrong. Magento expects a comma-separated file saved as UTF-8 without BOM. Some spreadsheet applications (Excel in particular) save CSVs with semicolons or Windows-1252 encoding by default. Open the file in a plain text editor to verify the format.

Rates show for some addresses but not others. You are likely missing wildcard fallback rows. If your table has specific rows for California and New York but no wildcard row for other US states, customers in Texas see no shipping options. Always include a catch-all row with asterisks.

Handling fee not applied. The handling fee in the table rate configuration is added on top of the CSV price. If you set a 10% handling fee and your CSV says $8.00, the customer sees $8.80. Make sure the fee type (fixed vs. percent) is set correctly.

Table Rates vs. a Custom Module: Which to Choose

Factor Table Rates Custom Carrier Module
Setup complexity Low, CSV upload in admin High, requires PHP development
Rate logic Destination + one condition column Unlimited, any PHP logic
Multi-carrier support One method only Multiple methods per carrier
Real-time rates No, static CSV values Yes, can call external APIs
Zip ranges Not supported Fully customizable
Dimensional weight Not supported Can calculate from item dimensions
Maintenance Re-import CSV when rates change Deploy code changes
Works on Shopify or Shopware No, Magento-specific No, Magento-specific

For most Adobe Commerce merchants with straightforward zone-based pricing, table rates are the right starting point. When your carrier contracts involve complex rules, dimensional weight, or real-time API rate calls, a custom module or a third-party extension gives you the flexibility that CSV rows cannot.

If you need help configuring table rate shipping or building a custom carrier module for your store, Bemeir’s Adobe Commerce team has implemented shipping solutions for merchants ranging from domestic-only stores to international BigCommerce migrations and multi-warehouse fulfillment operations. As a Hyva partner, we ensure your shipping configuration works correctly across both admin and storefront.

FAQ

Can I have multiple table rate methods showing at checkout?

No. Magento’s built-in table rate shipping supports one carrier with one method. If you need to offer “Ground” and “Express” with separate rate tables, you need a third-party extension like WebShopApps Matrix Rates or a custom carrier module that registers multiple methods within a single carrier class.

Do table rates work with Magento’s multi-source inventory (MSI)?

Table rates use the shipping address for rate lookup, not the source warehouse location. The rate a customer sees is based on their destination, not which warehouse ships the order. If you need origin-based shipping calculations that factor in warehouse location, you need a custom carrier or a real-time rate API from your carrier.

How do I set up free shipping above a certain order total?

Use the “Price vs. Destination” condition type. Add a row with the order subtotal threshold and a shipping price of 0.00. For example, to offer free US shipping on orders above $75, add a row with Country “USA,” Region “,” Zip “,” Order Subtotal “75,” and Shipping Price “0.00.” Keep a row for subtotal “0” with your standard rate so orders under $75 still get a price.

Can I import different table rates for different store views?

Table rate imports work at the website scope, not the store view scope. All store views under the same website share the same table rate data. If you need different rates for different store views (for example, different currencies), you need to set up separate websites in Magento, each with its own table rate import.

What happens if no row in the CSV matches the customer’s address?

Magento does not display the table rate shipping method at checkout. The customer sees no option for that carrier. This is why wildcard fallback rows are important. Without a catch-all row at the bottom of your CSV, customers from unmatched destinations get no shipping quote and cannot complete checkout.

Let us help you get started on a project with Magento 2 Table Rate Shipping: CSV Import, Weight and Destination Rules, and Custom Carrier Fallbacks on Adobe Commerce and leverage our partnership to your fullest advantage. Fill out the contact form below to get started.

more articles about ecommerce

Read on the latest with Shopify, Magento, eCommerce topics and more.