Skip to content
CMS Max Documentation

ShipStation

A shipping management plugin to automate and simplify order fulfillment and shipping logistics.

Overview

The ShipStation plugin connects your CMS Max store with your ShipStation account, automatically sending new orders to ShipStation so your fulfillment team can start processing and shipping right away. There is no need to manually export or re-enter orders — everything syncs automatically.

Note: The Ecommerce plugin must be installed and activated before you can use ShipStation.

Note: Your store needs a phone number. ShipStation puts it on every order as the phone number of the address the order ships from, and rejects orders without one.

Setting Up ShipStation

  1. Add your store's phone number in Store Settings > Store Information. If you have more than one store, or Multiple Stores is turned on, edit your first store under Stores instead.
  2. Go to Settings > Plugins in the admin panel
  3. Find ShipStation in the plugin list and open its settings
  4. Enter your ShipStation V2 API key. In ShipStation, go to Account > API Settings, choose V2 API and generate a key.
  5. Click Save and Install to activate the integration. Saving checks the key with ShipStation first.

While your store has no phone number, the settings page shows a warning with a link to add one, and you can't install or activate the plugin. Once it is installed, you can still change and save its settings, or deactivate it. While the plugin is active, the store's phone number is required and can't be removed. If an active plugin's store still has no phone number, the dashboard shows ShipStation can't receive your orders until your store has a phone number. Click Fix It to open the store, add the number and save.

ShipStation plugin settings page

Configuration Options

API Key

Your ShipStation V2 API key. This is required for the integration to work. To create one, go to Account > API Settings in ShipStation, choose V2 API and generate a key. V1 keys (an API key and secret pair) don't work.

Click Test Connection under the key to check it with ShipStation. It checks the key in the field, so you can try a new key before saving it. Spaces or line breaks around a pasted key are removed; a key with a space inside isn't accepted.

Saving also checks the key:

  • If ShipStation rejects a new key, nothing is saved and the page says so. Check that you copied the whole V2 key and that your ShipStation plan includes API access.
  • If ShipStation rejects the key that is already saved, your other changes are saved and the page warns you. Orders can't reach ShipStation until you enter a working key.
  • When you reinstall the plugin, the key from the earlier install is still filled in. If ShipStation rejects it, the plugin isn't installed until you enter a working key.
  • If ShipStation doesn't answer, or answers with an error unrelated to the key, the settings are saved with a warning. Use Test Connection later to check the key.

You can check a key 5 times a minute, counting both Test Connection and saving. After that, wait a minute before checking a key, saving a new one, or installing the plugin.

A key that worked can stop working later, for example when it is regenerated in ShipStation or the ShipStation plan loses API access. When ShipStation rejects the saved key while sending an order, checking for shipped orders (every 15 minutes) or checking the key, the dashboard shows ShipStation is rejecting your API key, so orders can't reach ShipStation., with ShipStation's answer and when it came. It can't be ignored. The settings page shows the same warning above the API key. Click Fix It to open the settings, enter a working V2 API key and save. The warning goes away when you save a new key, or when ShipStation accepts the saved key again, such as on Test Connection. Orders placed while the key was rejected didn't reach ShipStation, so check ShipStation for them and add any that are missing.

Send Orders Automatically

When this option is enabled (the default), eligible new orders are sent to ShipStation automatically. ACH orders wait until their payment clears; orders that are cancelled or otherwise leave Processing before the queued sync runs are not sent. If you prefer to send orders manually or in batches, you can disable this option.

Fulfillment Methods to Send

Choose which fulfillment methods are sent to ShipStation. Only orders using a checked method are sent; if no method is checked, no orders are sent. When you first install the plugin every method is checked, so all orders are sent until you uncheck one — for example, leave just Shipping checked to send only shipping orders. The list shows your store's enabled fulfillment methods, including any custom ones. A fulfillment method or custom method you add later is not checked automatically; check it here to start sending its orders.

Orders the customer collects (in-store pickup, curbside pickup and custom methods) are sent with your store's address as the ship-to, under the customer's name, so nothing is shipped to the customer by mistake. Every order shows its fulfillment method in ShipStation's Custom Field 2.

ShipStation Store

ShipStation puts orders in a store. Unless you choose one, orders from CMS Max go to ShipStation's Api Shipments store, and ShipStation lists them under that name.

To list them under your store's name instead, rename that store in ShipStation: go to Settings > Selling Channels > Store Setup, edit Api Shipments and change its Store Name. Nothing needs to change in CMS Max. Place a test order afterwards and check that it shows up under the new name.

  • Store Name is shown on every order in ShipStation's Custom Field 3, up to 100 characters. Leave it blank to use the Store Name from Store Settings > Store Information (with more than one store, your first store's name). The field shows that name in grey while it's blank. It doesn't choose or rename the store in ShipStation.
  • ShipStation Store ID sends orders to that ShipStation store instead of Api Shipments. The ID is a number, such as 4491453, sometimes written se-4491453; either works, but a store's name isn't accepted. Leave it blank to keep using Api Shipments.

To find a store's ID, click Choose from your stores above the ShipStation Store ID field:

  1. Enter a ShipStation V1 API key and secret. ShipStation lists stores only through its older V1 API, so the V2 API key doesn't work here. In ShipStation, go to Account > API Settings, choose V1 API and generate a key and secret. CMS Max uses them only to list your stores, then clears them. It doesn't save them. Orders are still sent with your V2 API key.
  2. Click Next, then choose the store. Type to search by name or ID. Stores connected to a marketplace, such as Shopify, show it after their name, and stores with the same name and marketplace show their ID too. ShipStation might not take CMS Max orders in a store connected to a marketplace, so the page warns you when you choose one. The list opens on the store already in the field. If ShipStation doesn't list that store, the list opens empty and says so. With no Store ID, it opens on the store you made in ShipStation with the same name as the Store Name field (or, when that's blank, the store name in Store Settings), if exactly one store has that name.
  3. Click Use this store, then save your settings.

You can also ask ShipStation support for a store's ID. You can load your stores 5 times a minute.

After you save a new Store ID, the page reminds you to place a test order and check that it shows up in that store. ShipStation turns down orders sent with a Store ID it doesn't know, so if the order doesn't show up, check the ID or clear it so orders go to Api Shipments again. If your ShipStation webhook is set to one store, change it to All Stores or to the new store, so CMS Max still hears when those orders ship.

Neither setting changes orders already in ShipStation.

Webhook Configuration

The settings page displays a Webhook URL. Click the URL to copy it to your clipboard, then paste it into your ShipStation account under Settings > Integrations > Webhooks. Select the "On Orders Shipped" event. This allows ShipStation to notify CMS Max when an order has been shipped.

The webhook URL includes a secret token for authentication — treat it like a password. The URL only appears after your settings have been saved once, which generates the secret.

ShipStation webhook configuration section

When an Order Ships

When ShipStation tells CMS Max an order shipped, CMS Max asks ShipStation for the order's tracking about half a minute later, using the API key you already entered. CMS Max also checks ShipStation every 15 minutes, so tracking still comes back if a notice is missed or the webhook isn't set up. On the order page it then:

  • fills in the Tracking Number section with the tracking number, the carrier (for example UPS) and a link to the carrier's tracking page;
  • marks the order Shipped and Fulfilled.

This works for orders you buy a label for in ShipStation. Return labels are ignored. It also picks up an order you mark as shipped in ShipStation with a tracking number typed in, within about 15 minutes. For those orders, CMS Max links the tracking number for USPS, UPS, FedEx and DHL Express, and shows the carrier name without a link for other carriers.

A few things to know:

  • Only orders CMS Max sent to ShipStation are updated. CMS Max finds them by order number and by the store reference in Custom Field 1, so leave Custom Field 1 as it is.
  • CMS Max looks at orders that shipped in the last two weeks.
  • If you void a label and buy a new one, the new tracking number replaces the old one.
  • CMS Max brings each tracking number over once. If you later change the order's status back, or change or clear its tracking number, CMS Max leaves your change. Only a new label updates the order again, or, for an order without a label, marking it shipped again with another tracking number.
  • If you already typed a different tracking number on the order page, CMS Max keeps yours. The order is still marked Shipped.
  • Cancelled and refunded orders are not changed.
  • Only shipping orders are updated. An order on hold gets the tracking number but keeps its status.
  • An order already marked Shipped or Fulfilled by hand keeps its status. If it has no tracking number yet, CMS Max adds the one from ShipStation.

What Information Is Sent to ShipStation

When an order syncs to ShipStation, it includes:

  • Order number, date, and status
  • Customer email address and shipping details
  • Billing and shipping addresses
  • All ordered items, including SKUs, names, quantities, and prices
  • Each item's selected variant, product options and, for items priced by dimensions, the chosen size (for example Size: Large, Engraving: John, Size: 48" x 24"), shown on the line item in ShipStation
  • Order totals, including shipping and tax amounts
  • The weight (in pounds) and size (in inches) of the boxes the order packs into, packed the same way checkout packs a cart for carrier rates: from your products' weights and dimensions, or your store's default weight and dimensions for a product without them
  • Any note the customer left at checkout, shown in ShipStation as Notes from Buyer (internal order notes added by staff are not sent)
  • The shipping option the customer chose at checkout, shown in ShipStation as Requested with its carrier in front, the way ShipStation names its services (for example USPS Priority Mail or UPS Ground). A name that continues the carrier's name is joined to it (DHL Express and Express Worldwide show as DHL Express Worldwide). A name that already starts with the carrier, such as FedEx Ground, is shown as checkout showed it, and so are options without a single carrier: flat-rate and free shipping, an estimated rate, a mixed-cart option such as Priority Mail + Freight, and pickup, local delivery and custom methods. When the customer chose no option, it shows the fulfillment method instead (for example In-Store Pickup). ShipStation shows up to 100 characters. On its own it does not choose the carrier or service; you still pick those when you buy the label. ShipStation automation rules that look at the requested service apply to it
  • A store reference (cmsmax_<your-site>) in ShipStation's Custom Field 1, so your fulfillment team can trace which store an order came from
  • The fulfillment method (for example In-Store Pickup) in ShipStation's Custom Field 2
  • Your store name in ShipStation's Custom Field 3

Troubleshooting

Orders are not appearing in ShipStation:

  • Check that the ShipStation plugin is active in your Plugins page
  • Confirm that Send Orders Automatically is enabled in the plugin settings
  • Check that your store has a phone number. Orders placed while it had none were not sent; enter them in ShipStation.
  • Check the dashboard for ShipStation is rejecting your API key, or click Test Connection under the API key. If ShipStation rejects the key, enter a new V2 API key from Account > API Settings in ShipStation. Then check ShipStation for orders placed while the key was rejected, and enter any that are missing.
  • If you added a ShipStation Store ID, check it with Choose from your stores or with ShipStation support, or clear it to send orders to Api Shipments again.
  • Check Fulfillment Methods to Send — only orders using a checked method are synced, so make sure the order's fulfillment method is checked
  • Contact your site administrator to check whether there are any system errors being logged

Orders don't get a tracking number or the Shipped status when they ship in ShipStation:

  • Check that the Webhook URL from the settings page is added in ShipStation with the "On Orders Shipped" event, and that it's set to All Stores or to the store your orders go to.
  • Click Test Connection under the API key. CMS Max needs a working key to look up the tracking.
  • Check that the order was sent to ShipStation by CMS Max and that its Custom Field 1 still holds the store reference (cmsmax_<your-site>).
  • An order marked as shipped in ShipStation without buying a label is picked up within about 15 minutes. You can also type its tracking number on the order page.