Skip to content
CMS Max Documentation

Shippo

Multi-carrier shipping with real-time rates, label printing, and tracking for your online store.

Overview

The Shippo plugin connects your CMS Max store with a multi-carrier shipping platform that provides real-time shipping rates, label printing, and package tracking. Customers see accurate shipping costs at checkout based on their address, and you can print shipping labels directly from your admin panel.

Account Modes

Shippo offers two ways to connect:

Mode Best For
CMS Max Enterprise Stores that want a managed shipping account with no external setup
Custom Shippo Account Stores that already have a Shippo account or need full control over carrier relationships

CMS Max Enterprise

This is the default option. Your store uses a shared CMS Max Shippo account, so you don't need a Shippo or carrier account of your own. Saving the settings sets up your store's Shippo account; then enable the carriers you want to use (see Managing Carriers).

CMS Max pays Shippo for each label you buy, each shipping rate lookup, and each address check, and bills you for them once a month. The bill adds a per-label fee that depends on your CMS Max plan. A refunded label lowers your bill once Shippo has settled the refund, which can take up to two weeks, and the credit comes off your next bill if that month was already billed. The per-label fee is not refunded. Removing Shippo stops the charges, and calls made before the removal stay on your next bill. With a custom Shippo account, Shippo bills you directly and CMS Max does not charge you for labels.

Custom Shippo Account

If you have your own Shippo account, select this option and enter your API key. You manage your own carrier relationships directly through the Shippo portal.

Setting Up Shippo

  1. Go to Settings > Plugins in your admin panel
  2. Find Shippo and open the settings page
  3. Choose your Account Type (CMS Max Enterprise or custom account)
  4. If using a custom account, enter your API Key
  5. Click Save and Install

Shippo plugin settings page

Managing Carriers

Shippo only gets rates and buys labels from carriers that are turned on for your account.

  • CMS Max Enterprise -- After you first save the settings, the Shippo settings page shows Carrier Accounts. Tick the carriers you want (USPS, Canada Post or UPS) and save. Canada Post and UPS ask for a few account details first. No carrier is on until you do this, so your Shippo shipping methods get no live rates at checkout and you can't buy labels.
  • Custom Shippo Account -- Carriers (such as FedEx, UPS, and USPS) are connected and turned on in the Shippo portal. Once they're active there, they're available for rates and labels in your store.

On the CMS Max Enterprise account, while a Shippo shipping method is active and no carrier is enabled, the dashboard shows a notice and eCommerce > Store Settings > Shipping shows a No Shippo carrier enabled alert above the Shipping Methods table. Both link to Carrier Accounts on the Shippo settings page. The notice can't be ignored or hidden; it goes away once you enable a carrier, or turn off your Shippo shipping methods.

Filtering Carriers and Service Levels

You can restrict which carriers and service levels appear at checkout:

  • Allowed Carriers -- Select specific carriers to offer (leave empty to allow all connected carriers)
  • Allowed Service Levels -- Select specific service levels to offer (leave empty to allow all available service levels)

This is useful when you want to limit checkout options to only your preferred shipping methods.

Excluding Products from Carrier Rates

A Shippo shipping method's Exclude Products list (eCommerce > Store Settings > Shipping, edit the method in the Shipping Methods table) keeps those products out of carrier rates. When a cart mixes excluded products with other products, checkout asks Shippo to rate only the other products and ships the excluded ones with another of your shipping methods, such as a flat rate. The customer sees one combined option, for example UPS Ground + Flat Rate, priced as the carrier rate plus that method's charge for the excluded products.

If none of your other shipping methods can ship the excluded products — they are excluded there too, or fall outside those methods' weight, quantity, or price ranges — checkout doesn't offer the Shippo rates for that cart. Set up a method that covers those products so customers can still check out.

Restricted Products: Alcohol, Tobacco and Vapes

Carriers and Shippo limit what can be shipped. USPS doesn't ship alcohol. USPS, UPS and FedEx won't deliver vapes, e-liquids or cigarettes to customers, and FedEx doesn't ship any tobacco. Alcohol ships through Shippo only with UPS or FedEx, on the shipper's own carrier account with an alcohol shipping agreement, and an adult must sign for it.

The Restricted products section of the Shippo plugin settings tells CMS Max which products these are:

  • Alcohol categories -- Products in these categories (and their subcategories) are alcohol. Liquor Max beverages are alcohol automatically, so you only need this for alcohol that isn't a Liquor Max beverage.
  • Never ship with Shippo -- Products in these categories (and their subcategories) never get Shippo rates or labels. Use it for tobacco, cigars, vapes, e-liquids and anything else your carriers won't take.
  • Ship alcohol with my UPS or FedEx alcohol agreement -- Appears only for a store with the Liquor Max plugin on its own Shippo account, and is on by default. Alcohol needs an alcohol shipping agreement on your UPS or FedEx account and the licenses your state requires; untick it if you don't have them. Switching the account type doesn't change it. Without Liquor Max, alcohol never ships through Shippo. Alcohol can't ship on the CMS Max Enterprise account either, because Shippo's own carrier accounts don't allow it; a Liquor Max store with Shipping enabled sees a dismissible notice. Choose Fix It if you want to switch to your own account.
  • Calculate shipping rates regardless of liquor product shipping agreement -- Off by default. Useful when you still want to use Shippo to fetch shipping rates without having to activate liquor shipping on the account. With it on, checkout asks Shippo to rate alcohol as a regular shipment, without the alcohol flag or an adult signature, and shows only UPS and FedEx rates for a shipment that contains alcohol. When neither UPS nor FedEx rates it, or Shippo rejects the request (for example, an invalid address), checkout shows no Shippo rate for it, not even the method's estimated fallback rate; the estimated fallback rate applies only while Shippo can't be reached. You are responsible for following carrier alcohol rules when you ship it: USPS doesn't ship alcohol, and UPS and FedEx need an alcohol shipping agreement. Orders with alcohol still get no Shippo label, so ship them another way. It applies on the CMS Max Enterprise account and on your own account while alcohol shipping is off or the store doesn't have Liquor Max; it's hidden while Ship alcohol with my UPS or FedEx alcohol agreement is on, because alcohol is then rated as alcohol. The CMS Max Enterprise alcohol notice doesn't show while it's on.

An archived category still counts and shows as "(archived)" in the two category fields, so archiving a category doesn't send its products back to Shippo.

A product Shippo can't ship (a product in a Never ship with Shippo category, or alcohol while alcohol shipping is off or the store doesn't have Liquor Max, unless Calculate shipping rates regardless of liquor product shipping agreement is on) works like a product in the Shippo method's Exclude Products list: Shippo rates the rest of the cart, and another of your shipping methods, such as a flat rate, must ship it. If none can, checkout tells the customer the item can't be shipped by carrier, and they can choose pickup or local delivery if you offer them. An order with such a product, or with alcohol rated through Calculate shipping rates regardless of liquor product shipping agreement, has no Buy Shipping Label button; its Shipping Label section names the products Shippo can't ship. Ship it another way.

With alcohol shipping on, a cart or order with alcohol is always rated as an alcohol shipment that needs an adult signature, and only UPS and FedEx rates are shown. When neither UPS nor FedEx returns a rate for it, checkout shows no Shippo rate for the alcohol, not even the method's estimated fallback rate, because no label could be bought for it. The Create Shipping Label page says so instead of offering a rate.

Alcohol Shipping Status

Shippo can't tell CMS Max whether alcohol will get rates, so CMS Max checks. With Ship alcohol with my UPS or FedEx alcohol agreement on, it looks for a UPS or FedEx account of your own in Shippo, then asks it to rate a sample alcohol shipment. With Calculate shipping rates regardless of liquor product shipping agreement on, it asks Shippo to rate a sample regular shipment and looks for a UPS or FedEx rate. A box under the checkboxes shows the result only when there's a problem:

  • No UPS or FedEx account of your own -- connect your own UPS or FedEx account in Shippo. Shippo's built-in carrier accounts don't allow alcohol.
  • UPS and FedEx returned no alcohol rate -- your account most likely has no alcohol shipping agreement. Ask UPS or FedEx for one.
  • UPS and FedEx returned no rate -- with Calculate shipping rates regardless of liquor product shipping agreement on, no UPS or FedEx rate came back, so alcohol gets no Shippo rates. Enable UPS or FedEx under Carrier Accounts (CMS Max Enterprise) or connect one in your Shippo account, then save.
  • Your carrier settings hide UPS and FedEx -- UPS or FedEx returned a rate, but the carriers or service levels you allow under the Shippo settings leave out every UPS and FedEx rate, so alcohol gets no rates at checkout. Allow a UPS or FedEx service level, then save.
  • Couldn't check alcohol shipping -- Shippo may be down, or it refused the request. If you use your own Shippo account, check its API key, then try again. Opening the dashboard tries again in the background, at most every 10 minutes.

When the check passes, no box shows.

The check runs when you open the Shippo settings and no check has run yet (the page shows "Checking whether alcohol gets Shippo rates…" for a few seconds), when you save the Shippo settings after changing the account type, the API key, the carriers or service levels you allow, or either alcohol checkbox, and when you click Check alcohol shipping. It checks the saved settings, so save before checking a new API key or a checkbox you just changed. When a real checkout or label quote gets no alcohol rate, CMS Max checks again in the background a few minutes later (at most once an hour). If Shippo can't be reached then, the earlier result stays.

For a store with the Liquor Max plugin and Shipping enabled under Store Settings > Fulfillment Methods, the dashboard shows the problem under Needs attention until the check passes, so you know Shippo isn't showing rates for your alcohol. Opening the dashboard doesn't wait on Shippo: when no check has run yet, it starts one in the background and shows a problem, if any, the next time you open the dashboard. There is no periodic alcohol check. The notice can't be dismissed: fix the problem and click Check alcohol shipping, or turn off both alcohol checkboxes.

FedEx One Rate

For some services (such as FedEx 2Day), FedEx quotes two prices: the standard price and a FedEx One Rate price, which only applies to parcels shipped in FedEx One Rate packaging.

By default, checkout shows each service once, at its standard price. If FedEx quotes a service only as One Rate, checkout shows that price, labeled (One Rate).

To offer both prices, check Offer FedEx One Rate at checkout in the FedEx One Rate section of the Shippo plugin settings. The section appears only when a FedEx account is connected. With it on, checkout lists the One Rate price as a separate option labeled (One Rate), such as "Priority Overnight® (One Rate)". FedEx 2Day is the exception: checkout shows only its One Rate price, "2Day® (One Rate)", and shows the standard 2Day price only when FedEx quotes no One Rate price for the parcel. Turn it on only if you ship in FedEx One Rate packaging.

When you buy a label for an order, the rate list shows both prices, and the One Rate price is marked (One Rate, FedEx packaging). The price the customer chose at checkout is selected for you. Choose the One Rate price only if you are shipping the parcel in FedEx One Rate packaging.

Shipping Labels

Shippo generates shipping labels in your chosen format. The default is PDF, but you can also select PDF 4x6, PNG, or ZPLII (for thermal printers) in the plugin settings.

API Logs

The API Logs tab lists every call your site made to Shippo in the last 30 days. Filter by Method and Status:

  • Success and Error show calls that succeeded or failed. A label refund shows the result Shippo settled it to, not its first response.
  • Pending shows label refunds Shippo is still processing. Shippo can take up to 14 days to settle a refund.
  • No Rates shows rate requests that returned no shipping rates.

Click View on a row to see the request and response. Its Status field shows Shippo's first response, so a refund that later settled can show QUEUED there.

Enterprise Account Details

If you are using the CMS Max Enterprise account, you can optionally provide:

  • Name -- Overrides the default sender name on labels
  • Company -- Overrides the company name on labels
  • Email -- Overrides the contact email for shipping notifications

These fields are optional and only apply to Enterprise accounts.

Troubleshooting

No shipping rates appearing at checkout:

  • Check that the Shippo plugin is installed and active in Settings > Plugins
  • Verify that at least one carrier account is connected
  • Make sure the product weights and dimensions are set on your products
  • If using carrier or service level filters, confirm that the allowed options have not excluded all available rates
  • If the cart has alcohol or a product in a Never ship with Shippo category, Shippo doesn't rate that product; see Restricted Products. Without an alcohol agreement, Calculate shipping rates regardless of liquor product shipping agreement gets alcohol rated as a regular shipment
  • With alcohol shipping on, alcohol gets only UPS and FedEx rates, so connect a UPS or FedEx account that has an alcohol agreement

Label printing fails:

  • Check that your Shippo account (or the Enterprise account) has a valid payment method
  • Verify the shipping address is complete and valid

Error: "Enterprise plan selected but no managed Shippo account found":

You picked CMS Max Enterprise as your account type but the managed sub-account hasn't been provisioned yet. This happens when settings were saved partway through, or if account creation didn't finish.

To fix it:

  1. Go to Settings > Plugins > Shippo
  2. Confirm Account Type is CMS Max Enterprise License
  3. Verify the Your Name, Company, and Email under Enterprise Account Details are correct
  4. Click Save — this provisions your managed Shippo sub-account
  5. The Account Status indicator should change from Not Created to Active with an account ID

Until this is done, label purchases, refunds, and shipping rate quotes will all be blocked. This is by design — without a provisioned sub-account, transactions would otherwise be silently billed to the shared platform account with no record of which store made the purchase. Address validation continues to work in this state so customer-facing checkout flows degrade gracefully.

If you continue to see this error after saving, contact CMS Max support — there may be an issue creating your sub-account on the Shippo side (e.g., a duplicate email or a Shippo platform outage).