VibeFox SF 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.

SF Express account (for live prices only): live prices use the SF Express FengQiao open platform (open.sf-express.com). You need an SF Express monthly account and a developer account on FengQiao. Register there, create an application, add the API "Delivery time standard and price query" (EXP_RECE_QUERY_DELIVERTM) to it and copy the customer code and the checkword. The sandbox and production checkwords differ. If you only use the price table, you do not need an SF Express account.

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_sf_express folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox SF 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. Fill in the price table and / or the fallback cost.

6. For live prices in mainland China, enter the customer code and the checkword, the sender province and city (or set a Chinese store address) and, if your store currency is not CNY, the currency conversion rate. Test with Sandbox and sandbox credentials first.

7. Add VibeFox SF Express to a shipping zone in WooCommerce > Settings > Shipping > Shipping zones, or turn on Ignore shipping zones and choose countries.

Configuration

All settings are on one page: WooCommerce > Settings > Shipping > VibeFox SF 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 SF Express prices are cleared. If live prices are partly set up, a warning above the settings lists the missing settings or the missing conversion rate.

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: SF Express.

Tax status: Taxable adds your store shipping tax on top of the cost, None does not. Choose None if the SF Express price already includes everything you want to charge.

SF Express FengQiao API (live prices) (optional, for delivery addresses in mainland China)

Customer code (partnerID): the customer code (顾客编码) of your FengQiao application.

Checkword: the checkword (校验码) of the same environment. It is used only to sign requests and is never sent or logged.

Sandbox: use the FengQiao sandbox for testing with sandbox credentials. Sandbox prices are not real. Switch it off in a live shop. Default: off.

SF Express product: which SF Express product price is shown.

Sender province: the province the parcels are sent from. Leave it empty to use the province of the store address in WooCommerce > Settings > General, when the store is in China.

Sender city: the standard Chinese city name, for example 深圳市. Leave it empty to use the store city, when the store is in China.

Currency conversion rate: SF Express prices are in CNY (yuan). If your store currency is not CNY, enter how many units of your store currency one CNY is worth. Without it, live prices are not used. If your store currency is CNY, prices are used as they are. Both a point and a comma are accepted as the decimal separator.

Price table and fallback (used for Hong Kong, Macao, Taiwan and other countries, when live prices are not configured, or when SF Express gives no price; prices are in your store currency)

Country prices: a table with a base price per country. The row * Any other country applies to all countries without their own row. A weight tier price above 0 replaces the base price for parcels in that tier: ≤ 1 kg, ≤ 2 kg, ≤ 3 kg, ≤ 5 kg and > 5 kg. A base price of 0 means free shipping. An empty base price means no price for this country, and the fallback cost is used.

Fallback cost: used when neither SF Express nor the table gives a price. Leave it empty to hide the method in that case.

Table / fallback price is: how table and fallback prices are charged.

Live SF Express prices are always for the whole order.

Conditions

Free shipping from: the cart subtotal from which shipping is free. Free shipping is offered only where the method has a price for the destination: a live price, a table row or Fallback cost. Leave it empty to never offer free shipping.

Minimum subtotal: show the method only when the cart subtotal reaches this amount. Leave it empty to always show it.

Min weight (kg): the minimum cart weight in kg. Product weights are converted from your store weight unit. 0 means no limit.

Max weight (kg): the maximum cart weight in kg. Default: 50. 0 means no limit.

Excluded shipping classes: hide the method if the cart contains products of these WooCommerce shipping classes.

Availability without shipping zones

Ignore shipping zones: offer the method for the countries below even if it is not added to a zone. When off, the method appears only in the shipping zones it is added to.

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.

Advanced

Debug log: writes price calculations to the WooCommerce log: WooCommerce > Status > Logs, source vfd-sf-express. API errors are always logged, even when this option is off. No checkword or customer addresses are written.

Remove data on uninstall: when on, deleting the plugin removes its settings, its shipping zone methods and caches. 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 subtotal and excluded shipping classes. If free shipping applies and the price table or Fallback cost has a price for the destination, the method is shown with a price of 0 and no request goes to SF Express. Otherwise the plugin asks SF Express for a live price first, and shows the method free only if one comes back.

For a delivery address in mainland China with the customer code and checkword set, the plugin sends SF Express your sender province and city, the customer's province and city, the cart weight and the cart volume (from products with all three dimensions). The request is signed with your checkword. SF Express returns prices in CNY, and the plugin converts the chosen one to your store currency.

SF Express recognises addresses by standard Chinese names. The customer's province comes from the checkout state field. The city must be written in Chinese, for example 广州市. For Beijing, Shanghai, Tianjin and Chongqing the city is filled in automatically. A city in Latin letters, such as "Guangzhou", gets the table price.

Each price is cached for an hour, so the same cart does not trigger a new request. A failed request is cached for 10 minutes, so the checkout does not wait for SF Express on every refresh. The HTTP timeout is 10 seconds.

If there is no live price, the price comes from the price table, then from Fallback cost. If neither applies, the method is hidden. The customer never sees an error. The error 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). English and Simplified Chinese translations are included.

The plugin calculates prices only. It does not create waybills or labels, create orders in SF Express, book pickups, cancel or track shipments. Create and track shipments in your SF Express account as usual. Customers cannot choose an SF service point or locker. SF Express is used as a door-to-door courier. Live prices exist only for delivery addresses in mainland China. The plugin was built against the FengQiao documentation and mocked responses, so confirm the prices with your SF Express account (sandbox first) before going live.

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 SF 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, SF 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

SF 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 subtotal and Excluded shipping classes. Check that the table or Fallback cost has a price for the country.

The price comes from the table, not from SF Express: live prices need the customer code and checkword, a sender province and city, a delivery address in mainland China with a province and a Chinese city name, and (for non-CNY stores) the currency conversion rate. Open WooCommerce > Status > Logs, source vfd-sf-express, to see the reason. A failed request is retried after 10 minutes.

Error A1006 in the log: invalid signature. The checkword is wrong or belongs to the other environment. Check the Sandbox setting.

Error A1004 in the log: the price query API is not added to your FengQiao application.

Hong Kong: works with the price table and the fallback cost. The FengQiao price query is for mainland China addresses.

Rates look outdated after a change: save the settings page. This clears the cached SF Express prices.

For developers: the filter vfd_sfex_quote_request changes the price request, for example to another product code. vfd_sfex_api_url changes the gateway URL.

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 prices are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

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