Shipping Matrix

VIDEO WALKTHROUGH

Shipping Matrix: setup guide

2:39

Recorded on version 1.0.2 · Narrated walkthrough · English captions

Jump to a chapter 8 chapters

1. 0:00Set up Shipping Matrix
2. 0:12Open settings and choose scope
3. 0:33Choose website scope and condition
4. 0:52Review destination and fees
5. 1:13Export before replacing a rate table
6. 1:33Import and test checkout boundaries
7. 1:56Save and verify your setup
8. 2:17Your setup checklist

Read the full video transcript

Shipping Matrix 1.0.2 — Magento Admin setup

00:00:00 — Set up Shipping Matrix
Welcome to the Agentic Ecom Shipping Matrix Admin guide. We'll walk through the main setup screens and the checks to make before using the module. This guide assumes the extension is already installed.

00:00:12 — Open settings and choose scope
Start in Magento Admin and open Stores, Configuration. Choose Delivery Methods. Check the Scope selector before editing. Use the appropriate website or store view where the setting supports it. The screen values here are a demonstration; enter the settings and service details that belong to your own store.

00:00:33 — Choose website scope and condition
Shipping Matrix is under Sales, Delivery Methods. Select the website whose rates you are managing. Enable the carrier, choose its displayed title and select one Condition: package weight, order subtotal or item count. Each website and condition has its own rate table.

00:00:52 — Review destination and fees
Review applicable countries, handling fee and the message for an unmatched destination. Leave Use Numeric Zipcode Ranges off for alphanumeric postcodes such as those used in the United Kingdom. When numeric ranges are enabled, both bounds must be numeric and the range includes both ends.

00:01:13 — Export before replacing a rate table
Import and Export are available at website scope. Export the current table as a backup. Your C S V needs the exact nine-column header shown in the written guide. Prepare the table for the selected condition and avoid duplicate or overlapping bands for the same destination and named shipping method.

00:01:33 — Import and test checkout boundaries
Select the rate file and save the configuration only when its website and condition are correct. A valid import replaces that table. Test representative destinations, exact band boundaries, a fallback and an unmatched address in checkout. Use a real cart estimate for the final shopper price; the read-only rate preview is not a cart quote.

00:01:56 — Save and verify your setup
When your required settings are complete, use the screen's Save control and wait for Magento's confirmation. Then reopen the record or configuration and check the saved values at the intended scope. If the storefront still shows earlier settings, refresh the relevant caches. Test your own configuration before using it with customers.

00:02:17 — Your setup checklist
That's the Admin setup walkthrough for Shipping Matrix. Check permissions and scope, review the module-specific settings, then save and verify a small staging example. Use the written guide at user guides dot Agentic Ecom dot net for installation details, complete field references and any separate storefront integration steps.

Download videoEnglish captionsDownload transcript

Shipping Matrix 1.0.2 adds a shipping carrier with rates imported from a CSV file. Choose one condition for each rate table: package weight, order subtotal or item count. At checkout, the carrier finds the most specific matching destination tier and offers the named methods whose inclusive bands cover the cart.

Compatibility and licence

The 1.0.2 archive was installed, upgraded, compiled and tested on Magento Open Source 2.4.9 with PHP 8.5.10. Test it with your theme, rates and websites in staging. Other Magento editions and PHP combinations require separate qualification.

A one-time purchase includes 12 months of updates and support. Renewal is optional and never billed automatically. An eligible standalone extension may renew at 60% of the then-current regular list price before the support term ends or within 30 days afterward, plus applicable tax. Purchased versions remain usable after the support term. Read the AgenticEcom licence for the terms governing your order.

Install

For an Adobe Marketplace purchase, configure repo.magento.com with your Marketplace access keys. A Marketplace purchase does not require a second AgenticEcom licence. For a direct AgenticEcom purchase, use the repository and key supplied with your order.

composer require agenticecom/module-shipping-matrix
php bin/magento module:enable AgenticEcom_ShippingMatrix
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

Configure the carrier

Open Stores → Configuration → Sales → Delivery Methods → AgenticEcom Shipping Matrix. Switch the scope selector to the website whose rates you want to manage. Enable the carrier, set its title and choose Condition: weight, subtotal or item count. Set applicable countries, an optional fixed or percentage handling fee, and the displayed error message for an unmatched destination.

Import and Export CSV appear at website scope. The selected condition determines which rate table is imported or exported. Each website can have its own rates.

Prepare a CSV

The first row must contain these nine column names in this order:

Country,Region/State,City,Zip From,Zip To,Condition From,Condition To,Price,Shipping Method
GB,*,*,*,*,0,9.99,5.99,Standard
GB,*,*,*,*,10,30,9.99,Standard
GB,*,*,*,*,0,30,12.99,Express
GB,*,London,*,*,0,30,7.99,Same-day
*,*,*,*,*,0,1000000,19.99,Worldwide Flat

* means any value. Country accepts a Magento ISO-2 or ISO-3 code, region accepts a code for that country, and city and postcode accept literal values. City matching is case insensitive. Condition From and Condition To are inclusive; for one destination and method, bands such as 0–9.99 and 10–30 do not overlap. Bands 0–10 and 10–30 overlap at 10 and the importer rejects them. Different named methods can share a band.

Postcodes

Leave Use Numeric Zipcode Ranges off for alphanumeric postcodes such as UK postcodes. When it is on, both postcode bounds must be numeric and the range includes both ends. Test a postcode at each boundary.

Import and export

1. At website scope, export the current table as a backup.
2. Choose the condition that your CSV describes.
3. Select the CSV in Import and save the configuration.
4. Test representative checkout destinations and exact band boundaries.

A valid import replaces the existing rows for that website and condition. If the header or any row is invalid, the import fails and the existing table remains intact. The importer rejects duplicate rows and overlapping bands for the same destination and method. Country and region codes are checked against Magento’s directory data.

How checkout uses the table

The carrier evaluates the destination and the selected cart condition. A city or postcode-specific row can take precedence over a broad country row; a global * row can provide a fallback. Within the winning destination tier, matching named methods such as Standard and Express can both be offered. A handling fee and free-shipping state may change the final checkout price.

If no rate matches, use Show Method if Not Applicable and Displayed Error Message to decide whether to show the carrier with a message or hide it. Check a specific destination, a global fallback, an exact band boundary, a free-shipping cart and an unmatched destination before going live.

Headless checkout and GraphQL

A headless storefront gets calculated checkout options through Magento’s standard cart shipping-address and estimate-shipping-methods flow. Shipping Matrix also exposes this read-only preview:

{
  shippingMatrixRates(country_id: "GB", region_id: 0, city: "London", postcode: "SW1A 1AA") {
    shipping_method
    price
    condition_from_value
    condition_to_value
    dest_city
    dest_zip
  }
}

The query returns configured candidate rows for the current website and destination while the carrier is enabled. It is not a cart quote. It does not apply cart weight, subtotal, discounts, tax or handling fees. Use the standard cart estimate for a final shopper-facing shipping option.

Troubleshooting

• No method appears: check Enabled, website scope, applicable countries, condition, destination fields and an exact inclusive band boundary. Check the global fallback and unmatched-method settings.
• Wrong method appears: check for a more specific city, region or postcode row. Export the website table and inspect the selected condition.
• Import fails: use the exact nine-column header and valid country/region codes; remove duplicate or overlapping bands for the same destination and method. The existing table stays intact after a rejected import.
• UK postcode range does not match: disable numeric range mode and use an exact postcode or a * wildcard. Numeric range mode only supports purely numeric postcodes.
• A frontend still shows an old rate: clear Magento configuration/full-page cache and any external storefront or CDN cache, then re-estimate the cart.

Support: support@agenticecom.net. Include Magento/PHP versions, website scope, a redacted CSV example and the destination/cart conditions.

1.0.2 release notes

This release qualifies Magento Open Source 2.4.9/PHP 8.5, makes CSV replacement atomic, validates duplicate and overlapping bands, corrects website and destination matching, preserves shared quote-request values, exports safely escaped CSV, and clarifies the GraphQL preview’s scope.