VibeFox ShipStation for WooCommerce — Help

Requirements

WordPress: 5.8 or later.

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

PHP: 8.0 or later.

ShipStation account: connect your carriers in ShipStation (Settings > Shipping > Carriers), then copy the API Key and API Secret from ShipStation > Settings > Account > API Settings. API access depends on your ShipStation plan. If the page is not available, your plan does not include API access. The plugin uses ShipStation API V1 (API Key and API Secret). ShipStation API V2 accounts with a single API key are not supported. Without keys, only the fallback prices are used.

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

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Shipping > VibeFox ShipStation, 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. Paste the API Key and API Secret, enter the ship-from postal code and save. The page now lists the carrier codes of your account. Enter the one(s) you want in Carrier codes and save again.

6. If your store currency is not the currency of your ShipStation account, set Exchange rate.

7. Optionally fill in the fallback prices.

8. Add VibeFox ShipStation 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 ShipStation. 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 Name.

Every time you save the settings, the cached ShipStation rates are cleared and the API key and secret are checked. The page then shows the carriers connected to your account with their codes, for example "stamps_com (Stamps.com), ups_walleted (UPS by ShipStation)". Warnings above the settings tell you when live rates cannot work: no keys, no carrier code, no ship-from postal code, a missing exchange rate, a failed connection check or carrier codes that are not connected to your account.

General

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

Name: the shipping method name shown at checkout. A zone can override it with its own Title. Default: ShipStation Shipping.

ShipStation account

API Key: the API Key from ShipStation > Settings > Account > API Settings.

API Secret: the API Secret from the same page.

Carrier codes: one or more ShipStation carrier codes, comma separated, for example stamps_com, ups_walleted. Up to 5 codes are used, with one API request per carrier. The cheapest rate of these carriers is shown. Take the codes from the list shown after saving.

Allowed services: optional, comma separated ShipStation service codes, for example usps_priority_mail, ups_ground. Leave it empty to show the cheapest service of the carriers above.

Package code: "package" (the default) rates your own box and leaves out carrier envelopes and flat rate boxes. Leave it empty to rate every package type the carrier offers.

Ship from

Ship-from postal code: required for live rates. ShipStation rates from the postal code only, and it must be in the country of your ShipStation account. Leave it empty to use the store postcode from WooCommerce > Settings > General.

Rates

Parcels: how the cart is sent to ShipStation.

One parcel per order (the cart is packed into one box): all items are stacked into one box and rated once.

One parcel per item (every unit ships in its own box): every product is rated as its own parcel and the rate is charged for each unit. Fallback prices are charged per unit as well.

ShipStation account currency: the currency ShipStation returns rates in: USD, CAD, GBP, AUD, NZD or EUR. Default: USD (US accounts).

Exchange rate: the price of 1 unit of the account currency in your store currency, for example 0.92. Needed only when the store currency differs from the account currency. Without it, live rates are not used and the fallback prices apply. Exchange rates are not updated automatically.

Tax status: Taxable lets WooCommerce add tax on shipping by your tax rules, None does not. ShipStation rates do not include sales tax.

Fallback prices (used when there is no live rate: no API keys, ShipStation unreachable, no carrier rates for the address; prices in your store currency; leave the table and Other countries empty to hide the method in that case)

Prices by country: a table with a base price per country and size columns by parcel weight: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg and XL >5 kg. Click + Add country to add a row and the cross to remove one. An empty size uses the base price. A base price of 0 means free shipping. The row * Default (all other countries) applies to countries without their own row.

Other countries: the price when the table has no price for the country. Leave it empty to hide the method in that case.

Conditions

Free shipping from: the cart subtotal from which shipping is free. No ShipStation request is made then. Leave it empty to turn it off.

Minimum subtotal: show the method only if the cart subtotal is at least this amount. Leave it empty to always show it.

Minimum weight: the minimum cart weight, in your store weight unit, to show this method. 0 means no limit.

Maximum weight: the method is hidden above this cart weight, in your store weight unit. 0 means no limit.

Disabled shipping classes: hide the method if the cart contains a product of one of these WooCommerce shipping classes.

Availability without shipping zones

Ignore shipping zones: offer the method for the countries below, whether or not it is added to a zone.

Countries: the destination countries for that mode. Leave empty to use all countries the store ships 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 ShipStation requests to WooCommerce > Status > Logs, source vfd-shipstation. API errors are always logged, even when this option is off. The API key and secret and customer addresses are never logged. The postcode is masked.

Remove data on uninstall: when on, deleting the plugin removes its settings and its shipping zone methods. Deactivating the plugin never deletes settings.

How it works at checkout

When the customer enters a delivery address, WooCommerce asks the plugin for a rate. The plugin first checks the conditions: cart weight, minimum subtotal and disabled shipping classes. If free shipping applies, the method is shown with a price of 0 and no request goes to ShipStation.

The plugin then sends ShipStation the ship-from postal code, the destination country, state, city and postcode, the parcel weight and the box size. No request is made before the customer has entered a postcode. Countries without postcodes get the fallback prices. Weights and dimensions are converted from your store units. Items are stacked into one box. If a product has no dimensions, the parcel is rated by weight only.

ShipStation is asked once per carrier code. The plugin shows the cheapest allowed rate, converted to your store currency, under the method name.

Each answer is cached for 1 hour. When ShipStation answers without a usable rate, the answer is remembered for 10 minutes. When ShipStation rejects the keys or is unreachable, requests are paused for 5 minutes. After a rate limit, the pause follows ShipStation's reset time. The request timeout is 12 seconds. Deactivating the plugin clears the cached rates.

If there is no live rate, the price comes from the fallback table, then from Other countries. If neither applies, the method is hidden. The customer never sees ShipStation error texts. Details go to the WooCommerce 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).

The plugin calculates rates only. It does not buy labels, create ShipStation orders or shipments, track parcels or handle returns. There are no pickup points, no choice between several services at checkout, no address validation, insurance, signature confirmation, packing into several parcels or rate markup.

Orders

The shipping line of the order stores the chosen Service, for example "USPS Ground Advantage - Package". You see it on the admin order screen and can create the matching label in ShipStation.

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 ShipStation. 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, ShipStation 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

ShipStation 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 Disabled shipping classes. Without a live rate, check that the country, * Default or Other countries has a price.

The checkout shows the fallback price instead of the ShipStation rate: check the warnings at the top of the settings page (keys, carrier code, ship-from postal code, exchange rate). Turn on Debug log and open WooCommerce > Status > Logs, source vfd-shipstation. The customer's postcode is required. No request is made before it is entered.

Which carrier code to enter: save the settings with the key and secret. The page lists the carrier codes of your account. Use one or more of them.

The rate differs from ShipStation: the parcel is built from the product weights and dimensions, with the items stacked into one box. Products without dimensions are rated by weight only. Rates are cached for 1 hour. Save the settings to clear the cache.

For developers: the filters vfd_shst_rate_request, vfd_shst_selected_rate and vfd_shst_api_url change the rate request per carrier, the chosen rate and the API base 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 the settings and only clears cached rates. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin, the cached rates and the saved carrier list are always removed. Settings and zone methods are removed only if Remove data on uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their shipping lines.

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