Saudi National Address in Magento 2: How to Collect, Validate and Store the Short Addres

From 1 January 2026, parcel delivery companies in Saudi Arabia must stop any shipment that does not have a National Address according to a rule set by the Transport General Authority (TGA). I noticed that the rule is meant to make deliveries more accurate and logistics work smoother in a sector that is growing fast. In Ramadan 2025, licensed delivery companies sent more than 26 million postal packages, which is 18 percent more than the previous year. For a Magento 2 store that ships to Saudi Arabia, an address that used to be optional is now a piece of information that couriers can use to refuse a parcel.

Most Magento checkout pages do not include a field for the address. The guide explains what the short address is, what the rule means for merchants, and how to collect, check, and keep the address, including when a Google Maps pin is helpful and when it is not.

What the National Address and the Short Address Actually Are

The Saudi National Address is run by Saudi Post (SPL). According to SPL, the full address has six parts: building number, street name, district, city, postal code, and a secondary number. The short address is a compact version of the same thing, made of four letters followed by four digits. SPL describes the letters as assigned from the postal code and the digits as the building number, with RAGI2929 as its own example.

Customers do not need to work this out themselves. The TGA says individuals can look up their National Address through the National Address platform, Absher, Tawakkalna, Sehhaty and SPL, which is worth telling them at checkout.

What the Rule Means for a Magento Merchant

The TGA decision puts the responsibility on parcel carriers, not on the store. Licensed carriers must not accept any shipment that does not include an address. In real-world practice, this impacts the merchant because a rejected parcel means a failed delivery, a delay, and often a return. According to Salasa’s merchant FAQ, the rule applies to cash on delivery, prepaid, domestic and international shipments into the Kingdom. This means cross-border sellers are not exempt.

Most logistics providers guide merchants to treat the eight-character address as the field to collect. Sources such as Quiqup advise adding a required field for Saudi destinations. Because carriers differ in what their systems accept, confirm with your carrier whether they want the short address, the full National Address, or both. Salasa reports adopter results such as ninety-six percent first-attempt delivery success and twenty percent fewer address-related returns. Those figures come from a logistics vendor, so treat them as directional rather than guaranteed.

Collect, Validate, Store at a Glance

Step 1: Collect It at Checkout

Magento's default checkout asks for street, city, region, and postcode. There is nothing for a Saudi short address. Adding one means a custom address attribute, a module that provides the field, or custom development. Whatever way you choose, design choices matter more than the method used.

• Display the field when the country is Saudi Arabia and make the field required for those orders so the customer cannot proceed without the field.

• Label the field, for example, "National Short Address (4 letters + 4 digits)" with a placeholder such as RRRD2929.

• Include help for the field. Provide a link that explains where to find the code in Absher SPL or the National Address platform. A customer who does not know the field is not stuck at the last step.

• Offer the field in the My Account address book so returning customers are not asked again and the saved address already carries the code.

Step 2: Validate It in Two Layers

Layer 1: Check the format

The short address is four letters followed by four digits. This pattern helps catch typing mistakes. Make sure to trim any spaces and convert the address to uppercase before checking. Do the format check both on the server and in the browser. That way, even if someone skips the browser check, the server will still catch errors.

^[A-Za-z]{4}[0-9]{4}$

A format check only confirms the code has the shape. It does not prove that the address actually exists.

Layer 2: Confirm the address exists

The stronger check relies on a lookup against SPL's National Address data. A Shopify implementation write-up from Techies describes the method: collect the short address, then validate it using SPL National Address APIs. This process resolves details like building number and street name with map drop-pin validation as a check. The same idea applies to Magento. A successful lookup allows you to pre-fill the rest of the address and flag any mismatch between the postal code and the city the customer entered.

• Decide in advance what happens if the lookup service is slow or unavailable: Should the order be. Should you accept a well-formed code and verify it later? Either choice is valid. The decision should be intentional and recorded in logs.

• Keep API credentials and usage terms with SPL or your chosen address-validation provider. Also cache results wisely to avoid calling the service with every keystroke.

Step 3: Store It Where Couriers and Support Can Use It

An address that is collected but never leaves the checkout does not help anyone. Save the address as its own attribute instead of hiding it inside the street line so the address can be validated, exported, and mapped.

• Save the address on the order address and on the customer's saved address.

• Show the address in the admin order view, order emails, invoices, and packing slips so the support and warehouse teams can see the address.

• Map it into your shipping integration. Carrier tools expect a dedicated field: the Saudi Address Pro plugin for WooCommerce, for instance, notes that it fills the ShortCode field in SMSA's shipment form automatically from the order. A Magento store needs an equivalent mapping into whichever carrier it uses.

Treat the stored code like any other address data under your privacy policy and retention rules.

Where a Google Maps Pin Fits, and Where It Does Not

A map pin and a short address are different pieces of data. A pin gives coordinates, which helps a driver find the right door and reduces typing errors. The short address is the official code carriers look for under the TGA rule. A pin supports delivery accuracy, but it should not be treated as a substitute for the National Address.

MageDelight's Locate Me at Checkout extension is listed as a Google Maps pin and Short National Address locator for Magento 2, which auto-detects the customer's location and supports the Short National Address for Saudi Post. Based on MageDelight's user manual, the map side works like this:

• A Google Address Picker can be switched on separately for the checkout shipping address, the checkout billing address, and the customer account address page.

• Customers open a Pin Location map to search for or drop a pin on their delivery point, and street, country, state, city, and postal code can be filled in from the selected location.

• The latitude, longitude, formatted map address, and area are saved with the order and shown read-only to admins and to the customer in their order view, and are saved to the address book when the customer chooses to save the address.

• The extension requires a Google Maps API key that you own. The key must have the Maps and Places APIs activated. The default map centre, zoom level, and size can be changed as needed.

• The extension works with Magento Open Source, Adobe Commerce and Adobe Commerce Cloud versions 2.4.0.x, through 2.4.9.x. The extension is also marked as Hyvä

Before you deploy the extension, test the live demo. Check how the short address field behaves in your store. Is the field required? How does the field validate? Where does the field store its data? Compare the results against the three stages mentioned earlier. If your carrier needs SPL lookup validation or a custom field mapping that the extension does not cover, MageDelight's Magento development services team can scope that as custom work.

Magento 2 Saudi Short Address Checklist

☐ Confirm with your carrier which address format they need for deliveries in Saudi Arabia.

☐ Add a short-address field that appears and is required when the country is Saudi Arabia.

☐ Include helper text or a link that tells customers where to find their address code.

☐ Check the format in the browser. Also, check on the server side to make sure it's correct.

☐ Use an SPL lookup to verify the address. Plan what to do if the lookup service is down.

☐ Check that the code is saved as an attribute on every order and every address in the address book.

☐ Make sure the code shows up in the panel in customer emails on invoices and on packing slips.

☐ Connect the code with your carrier system or with the process for printing labels.

☐ Test all parts on both desktop and mobile devices. Look at both English versions of the store if those are supported.

☐ Go over the setup with your carrier and your compliance advisor.

Common Mistakes to Avoid

✗ Leaving the field as text without any format checks so typos and placeholder values get sent to the carrier.

✗ Treating the postal code and the short address as if they are the same thing. The postal code has 5 digits; the short address has 8 characters.

✗ Assuming a map pin meets the National Address requirement.

✗ Collecting the code. Never sending it to the shipping label or carrier API.

✗ Requiring the field without explaining where to find the code, which causes customers to leave checkout.

✗ Assuming an extension makes the store compliant. Compliance depends on your carrier's rules and on the information being correct.

Treat the Short Address as Core Checkout Data

For stores that ship to Saudi Arabia, the National Address has changed from something that was nice to have into a field that decides if a parcel is accepted. The best way to handle this every time is to get it check the format and make sure it exists and ensure it gets to the courier. A map pin gives accuracy on top of that, but it is an extra to the short address, not a substitute.

If you want customers to mark a delivery location as part of this process, the MageDelights Locate Me at Checkout extension is worth trying in the demo along with the short-address steps mentioned above.

Frequently Asked Questions

Is the short address mandatory for every order to Saudi Arabia?

Since 1 January 2026, a TGA decision requires parcel delivery companies to refuse shipments without a valid National Address. The duty belongs to the carrier. In reality, it applies to every parcel a merchant sends using a licensed carrier. Make sure to check with your carrier to find out which format they accept.

What does a Saudi short address look like?

It’s four letters followed by four digits, like RRRD2929. The digits stand for the building number, and the letters come from the postal code.

Is the short address the same as the postal code?

No. The postal code is a 5-digit number and is one part of the full National Address. The short address is an 8-character code that maps to the whole address.

How can a customer find their short address?

According to the TGA, through the National Address platform, Absher, Tawakkalna, Sehhaty, or SPL.

Does a Google Maps pin replace the short address?

No. A pin records coordinates and helps with delivery accuracy, but the National Address is a separate, official identifier. Collect both where you can.

Does a Magento extension make my store legally compliant?

No. An extension can help you gather, check, and keep the data. Making sure everything is right depends on following your carrier's rules and on how correct the information customers provide is. Make sure your setup is right by checking with your carrier and a compliance advisor.