VibeFox ShipStation for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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 module 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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox ShipStation in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

4. Paste the API Key and API Secret, enter the ship-from postal code and click Save. The page now lists the carrier codes of your account. Enter the one(s) you want in Carrier codes and save again.

5. If your shop default currency is not the currency of your ShipStation account, set Exchange rate.

6. Optionally fill in the fallback prices.

On install the module creates the carrier ShipStation Shipping with the delivery time text ShipStation carriers (USPS, UPS, FedEx, ...). The carrier is assigned to all zones and all customer groups. You can change zones, customer groups, delivery time, logo and size limits in Shipping > Carriers. Do not set prices there: the price always comes from the module.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox ShipStation > Configure. Each section has its own Save button, which saves the whole page. Every save clears the cached ShipStation rates and checks the API key and secret. 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 at the top of the page 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. A warning also appears when the shop weight or dimension unit is one the module cannot convert. Set kg, g, lb or oz and cm, mm, m or in in International > Localization (Local units). A number field with a negative value or text that is not a number, or a Minimum weight above the Maximum weight, is reported as an error and nothing is saved.

General

Enable ShipStation shipping: turns the carrier on or off. This is the same switch as the carrier status in Shipping > Carriers.

Name: the carrier name shown to the customer at checkout. Default: ShipStation Shipping. Required, 64 characters at most.

Tax: the tax rule of the carrier, or No tax. ShipStation rates do not include sales tax. No tax shows them as quoted, a tax rule adds tax on shipping by your tax rules.

ShipStation account

API Key: the API Key from ShipStation > Settings > Account > API Settings. It is sent only to ShipStation and never logged. After saving, the field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

API Secret: the API Secret from the same page. It is kept the same way as the key.

Remove the saved API key and secret: appears once keys are saved. Tick it and save to remove both.

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. If you enter more, only the first 5 are kept and the page tells you so. 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 shop postcode from Shop Parameters > Contact > Stores.

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 shop default currency, for example 0.92. Needed only when the default currency differs from the account currency. Without it, live rates are not used and the fallback prices apply. Exchange rates are not updated automatically.

Fallback prices (used when there is no live rate: no API keys, ShipStation unreachable, no carrier rates for the address; prices in your shop default currency; leave the table and Other countries empty to hide the carrier 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 trash icon 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. A row without any price is not saved.

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

Conditions

Free shipping from: the cart subtotal (after discounts, before tax) from which shipping is free. No ShipStation request is made then. Leave it empty to turn it off.

Minimum subtotal: show the carrier only if the cart subtotal (after discounts, before tax) is at least this amount. Leave it empty to always show it.

Minimum weight: the minimum cart weight, in your shop weight unit, to show the carrier. 0 means no limit.

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

Availability without shipping zones

Normally the carrier is offered in its zones in Shipping > Carriers. Alternatively it can be offered by country.

Ignore shipping zones: offer the carrier for the countries below, whether or not their zone is assigned. While it is on, the carrier is added to all zones, also to zones created later. Switching it off removes those added zones again.

Countries: the destination countries for that mode. Leave empty to use all active countries of the shop. This field is used only when Ignore shipping zones is on.

Advanced

Debug log: logs ShipStation requests to logs/vfd_shst_debug.log.php in the module folder. The file cannot be opened from the web. 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.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when on, uninstalling the module deletes the settings, the carrier, the log and the ShipStation service saved with orders. When off, everything is kept for a re-install.

How it works at checkout

At the shipping step PrestaShop asks the module for the price. Only physical products count: virtual products add no weight and are not included in the subtotal. The module first checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum subtotal. If free shipping applies, the carrier is shown with a price of 0 and no request goes to ShipStation.

The module 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. 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 module uses the cheapest allowed rate, converted to your shop default currency. The price is then shown in the customer's cart currency.

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. Disabling the module 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 carrier is hidden. The customer never sees ShipStation error texts. Details go to the debug log.

If you edit the carrier in Shipping > Carriers after it has orders, PrestaShop saves it as a new carrier version. The module follows the new version automatically.

The module 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

When an order is placed with a live ShipStation rate, the chosen service is saved with the order. The back office order page shows it in a ShipStation block as Service, for example "USPS Ground Advantage - Package", so you can create the matching label in ShipStation. Later recalculations of the cart do not change it. Orders placed with a fallback price or free shipping have no service block.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox ShipStation is the first block on Modules > Module Manager > VibeFox ShipStation > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-shipping-shipstation and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the ShipStation carrier is not shown to customers at checkout and no rate is calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

Troubleshooting

ShipStation does not appear at checkout: check that the license is active and Enable ShipStation shipping is on. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group, or turn on Ignore shipping zones and check Countries. Check the weight limits and Minimum subtotal. Without a live rate, check that the country, * Default or Other countries has a price. Products can also be limited to certain carriers in the product page.

The checkout shows the fallback price instead of the ShipStation rate: check the warnings at the top of the module page (keys, carrier code, ship-from postal code, exchange rate). Turn on Debug log, reload the checkout and look at the Log field. 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.

ShipStation connection check failed: the message shows the reason. Check the API Key and API Secret, then save again to repeat the check.

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. Click Save on the module page to clear the cache.

The page says the ShipStation carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox ShipStation and choose Uninstall. The license key and the license status are always removed. The cached rates and the result of the connection check are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history), and the settings, the log and the service saved with orders are removed. If it is off, the carrier is only disabled and the settings and the service of placed orders are kept. Installing the module again, or a Reset, gives the carrier back the status it had before.

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