VibeFox SMSA Express for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

WooCommerce: 5.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

SMSA Express rate card: the prices for the price table come from your SMSA account or the SMSA sales team. Enter them in your store currency. If your rate card is in SAR, AED or another currency, convert it first.

SMSA passKey (for live charges only): live charges use the SMSA web service (SECOM, operation getShipCharges). SMSA issues the passKey on request: ask your SMSA account manager or write to info@smsaexpress.com and ask for access to the SMSA web service with your account number. The passKey may differ from the API key of the SMSA e-commerce portal. SMSA has no test (sandbox) server for this service.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the vfd_smsa_express folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox SMSA Express, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter your SMSA Express prices in the price table.

6. Optional: under Live rates (API) turn on Live charges, enter your SMSA passKey, the ship-from city and country, and, if your store currency is not SAR, the exchange rate.

7. Add VibeFox SMSA Express to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones (for example "Saudi Arabia"), or turn on Ignore shipping zones and choose countries.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox SMSA Express. They apply to every shipping zone. When you add the method to a zone, the zone window has only one field:

Title (zone): the name customers see for this zone. Leave it empty to use the global Method title.

Every time you save the settings, the cached SMSA charges are cleared. When live charges are on, warnings above the settings tell you about a missing passKey, ship-from city or exchange rate, or an empty price table.

General

Enable/Disable: turns the method on or off in all zones at once.

Method title: the shipping method name shown in the cart and at checkout. A zone can override it. Default: SMSA Express.

Live rates (API) (optional; if SMSA returns no charge, the price table is used)

Live charges: get the shipping charge from SMSA Express. Default: off.

SMSA passKey: the key of the SMSA web service (SECOM). If the log shows "Invalid Passkey", the key is not accepted by this service. Ask SMSA for a web-service passKey.

Ship-from city: the city your parcels are sent from, spelled as SMSA does, for example Riyadh, Jeddah or Dammam. Leave it empty to use the store city from WooCommerce > Settings > General.

Ship-from country: the country your parcels are sent from. By default it is your store country.

Shipment type: sent to SMSA as the shipment type. DLV (the default) is standard delivery. Change it only if SMSA gave you another code.

Currency of SMSA charges: SMSA returns every charge with its currency code, usually SAR (the default). A charge in any currency other than this one or your store currency is not used.

Exchange rate: the price of 1 unit of the SMSA currency in your store currency, for example 0.24. Not needed when both currencies are the same. Without it, charges in another currency are not used and the price table applies. Both a point and a comma are accepted as the decimal separator.

Prices (your SMSA Express rate card in your store currency; used when live charges are off, and as the fallback when SMSA returns no charge)

Price table: one row per destination country. Click + Add country to add a row and the cross to remove one. The row * All other countries applies to countries without their own row. Each row has a base price and weight columns: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL over 5 kg. An empty or 0 weight column uses the base price. A base price of 0 means free shipping. Rows without any price are dropped when you save. Both "9.99" and "9,99" are accepted.

Price for countries not in the table: used when the table has no row for the destination country (and no * row) or the row has no price for this weight. Leave it empty to hide the method in that case.

Price applies: how the price is calculated.

Product weights are converted from your store weight unit to kilograms.

Conditions

Minimum weight (kg): hide the method when the cart weighs less. 0 means no limit.

Maximum weight (kg): hide the method when the cart weighs more. Default: 30. 0 means no limit.

Minimum order amount: show the method only when the cart subtotal (after discounts, before tax) reaches this amount. Leave empty to always show it.

Free shipping from: the cart subtotal (after discounts, before tax) from which SMSA Express shipping is free. Free shipping is offered only where the method has a price for the destination: an SMSA charge, a table row or the price for countries not in the table. If the table has a price, no request goes to SMSA. Leave it empty to never offer free shipping.

Excluded shipping classes: hide the method when the cart contains a product from any of these WooCommerce shipping classes.

Tax status: Taxable adds WooCommerce tax to the shipping cost, None does not. Choose None if your prices (the table and the SMSA charges) already include tax, for example Saudi VAT.

Availability without shipping zones

Ignore shipping zones: offer SMSA Express for the countries below even if the method is not added to any shipping zone.

Countries: the destination countries for that mode. Leave empty to use all countries you ship to. This field is used only when Ignore shipping zones is on. A method added to a shipping zone always works for the countries of its zone.

Advanced

Debug log: logs every rate calculation to WooCommerce > Status > Logs, source vfd_smsa_express. No customer addresses and no keys are logged. Errors of live charges are always logged, even when this option is off. Turn the log off when you are done.

Remove data on uninstall: when on, deleting the plugin removes all SMSA Express settings and zone methods. Deactivating the plugin never deletes anything.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a price. The plugin first checks the conditions: delivery country, cart weight, minimum order amount and excluded shipping classes. If free shipping applies and the destination has a price, the method is shown with a price of 0.

With live charges on, the plugin sends SMSA your ship-from city and country, the customer's city and country, the shipment type, the parcel weight in kg and a cash on delivery amount of 0. SMSA answers with the charge and its currency. The plugin converts it to your store currency and shows it. A live charge is requested only after the customer has entered a city.

Each charge is cached for an hour, so the same cart does not trigger a new request. A failed request is cached for 5 minutes. After a timeout or server error, SMSA is not asked again for 2 minutes. After a rejected key, it is not asked again for 5 minutes. So the checkout never waits for a failing service on every refresh. The request timeout is 12 seconds.

Whenever SMSA returns no usable charge (no passKey, no city entered yet, missing product weights, an invalid key, a timeout, an error, no service to the city or an unknown currency), the price table is used. If the table and Price for countries not in the table give no price, the method is hidden. The customer never sees an error. The reason is written to the log.

The method works on the classic checkout and on the Cart and Checkout blocks. It is compatible with WooCommerce High-Performance Order Storage (HPOS). An Arabic translation is included.

The plugin only calculates the shipping price. It does not create SMSA shipments, print AWB labels, handle returns or track parcels. Cash on delivery and its fee are not included in the live charge. There is no SMSA retail point selector: the method is door-to-door delivery.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Shipping > VibeFox SMSA Express. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, SMSA Express is not shown to customers at checkout. Logged-in store managers still see it, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

SMSA Express does not appear at checkout: check that the license is active, Enable/Disable is on, and the method is added to the zone of the customer's country (or Ignore shipping zones is on and the country is allowed). Check the weight limits, Minimum order amount and Excluded shipping classes. Check that the country or * has a price, or that Price for countries not in the table is set.

Customers see the table price instead of the SMSA charge: SMSA needs the customer's city, so until it is entered the table price is shown. The table is also used when SMSA does not answer, rejects the key or the city, or returns the charge in a currency without an exchange rate. Open WooCommerce > Status > Logs, source vfd_smsa_express, for the reason.

"Invalid Passkey" in the log: the key is not accepted by the SMSA web service. Ask SMSA for a web-service passKey.

The customer's city is not accepted: SMSA expects its own city spelling. Developers can adjust the request, for example the city name, with the vfd_smsa_express_live_request_fields filter.

Tax is charged twice on shipping: your rate card or SMSA charges may already include VAT. Set Tax status to None.

Rates look outdated after a change: save the settings page. This clears the cached SMSA charges.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. Settings, zone methods and cached charges are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

SMSA Express is a trademark of its respective owner. This plugin is not affiliated with or endorsed by SMSA Express.