VibeFox ShipStation for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

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. The extension uses ShipStation API V1 (API Key and API Secret). Without keys, only the fallback prices are used.

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

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package vfd_shipstation-oc3-(version).ocmod.zip and the OpenCart 4 package vfd_shipstation.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_shipstation-oc3-(version).ocmod.zip. The extension adds no OCMOD modifications, so you do not need to refresh Extensions > Modifications. Instead of the Installer, you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox ShipStation and click Install (the green + button).

3. Click Edit (the pencil button) to open the settings page.

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

5. 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.

6. If your store default currency is not the currency of your ShipStation account, set Exchange rate. Optionally fill in the fallback prices.

7. Turn on Enable ShipStation shipping and click Save.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file vfd_shipstation.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the extension type Shipping. Find VibeFox ShipStation, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key and the settings as in steps 4 to 7 for OpenCart 3. The settings page and its fields are the same in both versions.

After install the method is off until you turn it on and save. If you install the extension again after an uninstall, the ShipStation settings you kept are used again.

Configuration

All settings are on the extension page: Extensions > Extensions > Shipping > VibeFox ShipStation > Edit. The sections are listed on the left. One Save button saves the whole page without reloading it. 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)". Only admin users with the modify permission for this extension can save the settings.

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 store weight or length unit is one the extension cannot convert. Use kg, g, lb or oz and cm, mm, m or in (System > Settings > Option). An invalid name, a number field or price cell with a negative value or text that is not a number, a Minimum weight above the Maximum weight, or a sort order that is not a whole number is reported as an error, and nothing is saved.

General

Enable ShipStation shipping: shows or hides the method at checkout. This is the extension status in Extensions > Extensions > Shipping.

Name: the shipping method name shown to the customer at checkout. Default: ShipStation Shipping. Required, 64 characters at most, without the characters < > ; = # { }.

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

Sort order: the position of the method among the shipping methods at checkout. A whole number.

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, for example 78703. ShipStation rates from the postal code only, and it must be in the country of your ShipStation account. OpenCart has no store postcode, so it is never taken from the store address.

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. This is the default.

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 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 store default 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 up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL over 5 kg. Click Add country to add a row. 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 method in that case.

Conditions

Free shipping from: the subtotal of the products that need shipping (after the coupon, before tax) 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 subtotal of the products that need shipping (after the coupon, before tax) is at least this amount. Leave it empty to always show it.

Minimum weight: the minimum cart weight, in your store weight unit (shown in the field name), to show the method. 0 means no limit (default).

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

Availability

Geo zone: offer the method only for addresses in this geo zone. All zones (default) means no limit. Not checked while Ignore shipping zones is on. Geo zones are managed in System > Localisation > Geo Zones.

Ignore shipping zones: offer the method for the countries below, whatever the geo zone.

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

Advanced

Debug log: logs ShipStation requests to storage/logs/vfd_shst_debug.log.php (on OpenCart 4 system/storage/logs/vfd_shst_debug.log.php). The file cannot be read 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. When the file reaches 5 MB, it is moved to vfd_shst_debug.old.log.php and a new log is started.

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 extension deletes the ShipStation settings and the log. When off (default), they are kept for a re-install. Cached rates are always removed. The ShipStation service of placed orders is always kept.

Import / Export

Export: click Download JSON to save the settings as a JSON file. The API key and secret are not exported.

Import: paste previously exported JSON and click Import to restore the settings, for example on another store. The values are checked like a normal save. The saved API key and secret are kept.

How it works at checkout

When OpenCart shows the shipping methods, it asks the extension for the ShipStation price. If a Geo zone is set (and Ignore shipping zones is off) and the address is outside it, the method is not offered. Only products with Requires Shipping set to Yes count: other products add no weight and are not included in the subtotal. The extension then checks the conditions: allowed countries (with Ignore shipping zones), cart weight and minimum subtotal. Gift certificates, reward points and store credit are not taken into account. If free shipping applies, the method is shown with a price of 0 and no request goes to ShipStation.

The extension then sends ShipStation the ship-from postal code, the destination country, state code, 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 extension uses the cheapest allowed rate, converted to your store default currency and rounded to its decimals. The price is then shown in the customer's currency with the tax of the selected Tax class.

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.

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 debug log.

The extension 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.

On OpenCart 4 the customer clicks Choose in the shipping method block of the checkout page and picks ShipStation in the window Shipping method options. The method works the same way as on OpenCart 3.

Orders

When an order is placed with a live ShipStation rate, the chosen service is saved with the order. Open the order in Sales > Orders: the ShipStation panel above the order history shows it as Service, for example "USPS Ground Advantage - Package", so you can create the matching label in ShipStation. In the per item mode, the services are listed separated by commas. Later changes of the cart do not change it, and the panel is also shown after you switch the method off. Orders placed with a fallback price or free shipping have no ShipStation panel.

OpenCart 4 keeps one order for the checkout and updates it each time the customer confirms again. The saved ShipStation service is updated with it. If the customer changes to another shipping method, or the fallback price applies now, the saved service is removed from the order.

License key

The extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox ShipStation is the first block on Extensions > Extensions > Shipping > VibeFox ShipStation > Edit, 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 store. Below them are the line Product: opencart-shipping-shipstation and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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 and no rate is calculated. An admin user who is logged in to the admin in the same browser still sees the method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. Existing orders are not affected.

When a license expires, the extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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. Check Geo zone (or, with Ignore shipping zones on, Countries), the weight limits and Minimum subtotal. Without a live rate, check that the country, * Default or Other countries has a price. Check that the products have Requires Shipping set to Yes.

The checkout shows the fallback price instead of the ShipStation rate: check the warnings at the top of the extension 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 extension page to clear the cache.

The page says "Warning: You do not have permission to modify VibeFox ShipStation!": your admin user group may only view the settings. Give the group the modify permission for extension/shipping/vfd_shipstation (OpenCart 3) or extension/vfd_shipstation/shipping/vfd_shipstation (OpenCart 4) in System > Users > User Groups.

For developers: the ShipStation API address can be replaced with the setting vfd_shst_api_url (for tests); it has no field on the settings page.

Uninstall

Go to Extensions > Extensions, choose the type Shipping and click Uninstall (the red − button) next to VibeFox ShipStation. The license key and license status of this extension are always removed. OpenCart always resets Enable ShipStation shipping, Sort order, Tax class and Geo zone. The cached rates and the result of the connection check are always removed. If Remove data on uninstall is on, the ShipStation settings and the debug log are deleted as well. If it is off, the other settings are kept and are used again when you install the extension again. Existing orders keep their shipping method, cost and ShipStation service.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox ShipStation in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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