Saudi Address Pro

By SaudiAddressPro

★ 5.0/5 (1 ratings)10+ active installationsVersion 1.1.1

Verify Saudi Short Addresses with SPL and print delivery labels to help couriers find the right address.

Description

Saudi Address Pro is the definitive address autocomplete solution for WooCommerce merchants operating in Saudi Arabia. Designed to meet the Transport General Authority (TGA) 2026 mandate, our plugin ensures every order is captured with a verified, 100% accurate National Address directly from the Saudi Post (SPL) database.

The Problem

In the Saudi market, address accuracy is the single biggest barrier to successful last-mile delivery. Customers often struggle to enter complex address details manually, leading to:

  • Failed deliveries and returns
  • Customer frustration and cart abandonment
  • Increased support tickets
  • Non-compliance with upcoming regulations

The Solution

Saudi Address Pro allows customers to enter a simple short code (e.g., “RCTB4359”), which instantly auto-fills the complete, official address details—including building number, street name, district, city, and postal code.

Key Features

  • Official SPL Database Integration – Connect directly to the authoritative Saudi Post National Address system
  • Smart Short Code Autocomplete – Customers type their 4-character, 4-digit code and address fields populate instantly
  • TGA 2026 Compliance Ready – Collect compliant addresses today, before the January 1, 2026 deadline
  • Classic & Block Checkout – Full support for both classic WooCommerce and the Gutenberg block-based checkout (WooCommerce 8.3+), with an AJAX session handler that ensures the short address is saved even when the Store API is used
  • Order Email Visibility – The saved Saudi short address is included in WooCommerce customer and administrator transactional order emails
  • SMSA eCommerce Integration – Short address auto-fills the SMSA create-shipment ShortCode field automatically — no manual entry when creating shipments
  • All 13 Saudi Regions Auto-Fill – State/region dropdown fills correctly for every city in Saudi Arabia, from Riyadh to smaller governorates like Sharurah, Dilam, and Tayma
  • Bilingual Support – Full Arabic and English support with RTL
  • Zero-Config Field Mapping – Works out of the box with standard WooCommerce checkout fields
  • Test Connection – Verify your API key works directly from the settings page
  • Short Address Delivery Labels – Print a Saudi Address Pro Delivery Label from a saved Saudi order, with the recipient, verified address, map QR and optional delivery instructions. Help couriers find the right address and reduce delivery errors.
  • Optional Delivery Instructions – Let customers save instructions with their order for display on the delivery label. Off by default; instructions are customer-provided, not verified by SPL.

Delivery Labels for Courier Handoff

Enable Saudi Address Pro Delivery Label in the plugin settings, then open WooCommerce → Orders, select a Saudi order and choose Print Saudi Address Pro Delivery Label below its shipping address. Print the branded or monochrome label, or save it as a PDF.

Use this additional address label alongside your courier’s shipping label. It does not buy postage, create a shipment, provide tracking or replace an official carrier label. Each label generation verifies the saved Short Address and uses your lookup allowance.

Labels and optional delivery instructions are off by default. An independent option can add a staff-only order link to the merchant’s existing new-order email; it does not attach a PDF or send a customer notification. Existing checkout behavior and settings are unchanged.

Why Choose Saudi Address Pro?

  • Reduce cart abandonment – Faster checkout with fewer keystrokes
  • Eliminate address errors – Verified data from official government database
  • Ensure compliance – Meet TGA 2026 requirements
  • Improve delivery success – Accurate addresses for first-time delivery

Requirements

  • WooCommerce 5.0 or higher
  • PHP 7.4 or higher
  • Saudi Address Pro API key (get one at saudiaddresspro.com)

Privacy Policy

Saudi Address Pro connects to the Saudi Post (SPL) National Address API to retrieve address data. Customer address queries are sent to our API server (saudiaddresspro.com) which forwards requests to the official SPL database.

We do not store customer personal data on our servers. API usage logs are retained for service quality and rate limiting purposes only.

When a customer saves a valid Saudi short address during checkout, the plugin stores that code with the WooCommerce order. It is shown only in the order’s normal WooCommerce transactional emails to the customer and store administrators; no additional address data is added by this feature.

For more information, see our Privacy Policy and Terms of Service.

Installation

  1. Upload the plugin files to the /wp-content/plugins/saudi-address-pro directory, or install the plugin through the WordPress plugins screen directly.
  2. Activate the plugin through the ‘Plugins’ screen in WordPress.
  3. Navigate to Saudi Address Pro in the admin menu.
  4. Enter your API key (get one at saudiaddresspro.com/dashboard).
  5. Click “Test Connection” to verify your API key works.
  6. Configure your preferred language and options.
  7. Save settings and you’re ready to go!

FAQ

How do I print a delivery label?

Enable Saudi Address Pro Delivery Label in the plugin settings. Open a Saudi order with a saved recipient and valid Short Address, then click Print Saudi Address Pro Delivery Label below the shipping address. Staff permission and a valid API key are required. The label is verified with SPL and uses your lookup allowance; it is an additional address companion, not an official carrier shipping label.

Do I need an API key?

Yes, a Saudi Address Pro API key is required. You can get one by signing up at saudiaddresspro.com. A 60-day free trial with unlimited validations is available.

Does this work with the new WooCommerce block checkout?

Yes! Starting from version 1.0.2, the plugin fully supports both the classic WooCommerce checkout and the new block-based checkout (default in WooCommerce 8.3+).

Does this work with guest checkout?

Yes, the widget works for both guest and registered customer checkout.

Can I use this with custom checkout plugins?

Yes, as long as the checkout plugin follows WooCommerce’s standard field naming conventions. For custom field mapping, you can listen for the saudi_address_selected JavaScript event.

Is the short address code required?

No, customers can search by typing their full address. The short code is an optional convenience feature that speeds up the process.

Does this validate addresses in real-time?

Yes, all addresses come directly from the Saudi Post (SPL) database and are verified at the time of selection.

Is Arabic supported?

Yes, the widget fully supports Arabic with proper RTL (right-to-left) layout. You can configure the language in the settings.

How can I verify the plugin is working?

Go to the Saudi Address Pro settings page in your WordPress admin and click the “Test Connection” button next to your API key. This will verify your API key and connection to our server.

What is the TGA 2026 mandate?

The Transport General Authority (TGA) of Saudi Arabia has mandated that all parcel deliveries must include a valid National Address starting January 1, 2026. This plugin helps you collect compliant addresses.

Changelog

1.1.1

  • Added: Optional staff-only Delivery Labels for saved Saudi WooCommerce orders, with recipient, verified Short Address, map QR and saved delivery instructions.
  • Added: Branded or monochrome preview with Print / Save as PDF, isolated from the WordPress admin origin.
  • Added: Optional delivery instructions saved with orders. Both instructions and labels remain off by default.
  • Added: Independent opt-in staff order link in the existing merchant new-order email. No PDF attachments or customer notifications.
  • Security: Label generation requires order permission and a per-order nonce, reads saved order data, and verifies the Short Address through the authenticated HTTPS API.
  • Compatibility: Uses WooCommerce order CRUD for both legacy and HPOS storage. Existing checkout defaults, plans and allowances are preserved.

1.1.0

  • Security: Checkout searches now run through a nonce-protected WordPress endpoint, keeping the merchant API key out of customer-facing JavaScript.
  • Security: API-provided address and error values are rendered as text instead of injected as HTML.
  • Verification: Short Address order metadata and SMSA prefill values are saved only after authoritative SPL verification in the current WooCommerce session.
  • Reliability: Verified selections are time-limited, bound to the active cart when available, and consumed after one order to prevent cross-order reuse.
  • Added: Optional secure map lookup modal at checkout. The embedded lookup returns only a verified short address through an origin- and nonce-checked browser message, then saves it for both classic and block checkout.
  • Security: The map iframe receives no merchant API key. It uses the existing first-party signed provenance path when an in-app webview suppresses Referer headers.
  • Fixed: Short address code now saves correctly on block-based WooCommerce checkout — the widget uses an AJAX session handler so the Store API captures the code even though it does not submit classic POST fields
  • Fixed: Region/State field now populates for customers in smaller Saudi cities — all 13 regions resolved via SPL RegionId mapping and server-side city lookup, no longer dependent on RegionName being present in the API response
  • Improved: SMSA eCommerce ShortCode pre-fill is now more reliable across all checkout types
  • Improved: Saved Saudi short addresses are shown in WooCommerce customer and administrator transactional order emails; output is limited to a valid short code and uses WooCommerce order CRUD for HPOS compatibility

1.0.10

  • Fixed: Region/State field now populates correctly at checkout — city name is mapped to the WooCommerce SA state code (SA-01–SA-13) even when the SPL basic API endpoint is in use (no RegionName dependency)
  • Fixed: SMSA eCommerce create-shipment form now has the Short National Address (ShortCode) field pre-filled automatically from the WooCommerce order

1.0.9

  • Fixed: Region/State field now populates correctly at checkout — SPL region name is mapped to the WooCommerce SA state code (SA-01–SA-13)
  • Fixed: Short address code is now written to _billing_short_address order meta so SMSA eCommerce shipping labels are populated automatically

1.0.8

  • Fixed: Saudi short address code is now saved to the WooCommerce order and visible in the admin order detail screen under shipping address

1.0.7

  • Fixed critical bug: replaced wp_kses_post() with direct output in render_classic_widget() and render_footer_widget() — wp_kses_post() strips elements by design (it is meant for post content), causing the search field to silently disappear. All dynamic values inside get_widget_html() are already escaped with esc_html()/esc_attr(), so the wrapper was both redundant and harmful.

1.0.6

  • Widget now automatically positions above the Street Address field in classic checkout for better UX (customers enter short code first, address fields auto-fill below)
  • Renamed label to “Saudi National Short Address” (Arabic: العنوان الوطني المختصر) to better reflect the short-code nature of the field
  • Hardened input CSS with !important overrides to prevent aggressive theme styles from collapsing the search field

1.0.5

  • Internal improvements

1.0.4

  • Updated WC tested up to 10.6 — removes compatibility warning for stores on WooCommerce 10.x
  • Fixed output escaping to comply with WordPress security coding standards
  • Added translator comment for internationalization support
  • Updated Tested up to header to WordPress 6.9

1.0.3

  • Fixed critical infinite loop in WooCommerce block checkout (WC 8.3+) caused by MutationObserver feedback cycle
  • Improved widget stability: debounced visibility toggling and guarded DOM mutations prevent re-entry loops
  • Widget uses non-animating show/hide in block checkout to avoid DOM mutation cascades
  • Observer auto-cleanup: retry interval stops once widget is positioned and fields are detected
  • Fixed field highlight class changes from re-triggering the block checkout observer
  • Improved region selection and field value setting with mutation guards

1.0.2

  • Added full support for WooCommerce block-based checkout (default in WooCommerce 8.3+)
  • Added “Test Connection” button in admin settings to verify API key
  • Added widget label for better customer clarity (“Saudi National Address”)
  • Improved field detection for block checkout with MutationObserver
  • Added request timeout handling (10 seconds) to prevent stuck searches
  • Fixed search request cancellation when typing quickly
  • Better React-based checkout field value setting for block checkout compatibility
  • Updated WC tested up to 9.6

1.0.1

  • Improved compatibility with caching and optimization plugins (WP Rocket, LiteSpeed Cache, W3 Total Cache)
  • Fixed address search reliability when JavaScript minification is enabled
  • Better error messages in Arabic and English

1.0.0

  • Initial release
  • WooCommerce checkout integration
  • Address autocomplete with short code support
  • Admin settings page
  • Arabic and English language support
  • HPOS (High-Performance Order Storage) compatible