ShipStation

The ShipStation app sends your Swell orders to ShipStation, where you pick, pack and buy labels. When you buy a label, the app adds a shipment to the Swell order with the carrier, tracking number and the items in the package, and the order's fulfillment status updates to match.

The app replaces Swell's built-in ShipStation integration. It also sends order edits, payment and hold changes and cancellations to ShipStation, records partial shipments with their item quantities, and shows a sync status on each order.

Install ShipStation from the Swell App Store, and set it up in your test environment before the live one.

If the built-in ShipStation integration is on when you install the app, Swell asks how to handle the conflict. Click Disable conflicting integration to turn off the built-in integration and install the app. Ignore conflict installs the app and leaves the built-in integration on. To turn it off later, go to Integrations, open ShipStation and click Deactivate.

curl -X POST "https://<store-id>.swell.store/functions/shipstation/setup" \
  -u "<store-id>:<secret-key>"

When an order is paid, or submitted if Push orders to ShipStation is set to that, the app creates it in ShipStation. The order is sent with its shipping and billing addresses, the customer's email, the totals, the order notes as internal notes, the gift message and the shipping service the customer chose. Each item is sent with its product and variant name, SKU, quantity, weight, product options such as size or engraving, and the unit price the customer paid, including tax and less discounts.

With Send existing orders on, every 5 minutes the app sends up to 5 paid, open orders that still have items to ship and have no sync status, oldest first. After you set up the app, this sends the orders that were already waiting to ship, up to 60 an hour, until none are left. It also sends any other paid order the app hasn't sent, for example one paid while Enable ShipStation sync was off. Orders whose send failed aren't sent again by this check. While Push orders to ShipStation is Only when re-synced manually, this check sends nothing.

With Sync order edits on, an order is sent again when its shipping details, billing address or items change in Swell. With Sync cancellations on, a canceled order is marked cancelled in ShipStation, and its status is Canceled. Both apply only to orders ShipStation already has, as do payment and hold changes.

An edit or a payment or hold change that leaves the order as ShipStation already has it isn't sent. That includes the item update Swell makes when the app records a shipment, so recording a label doesn't send the order again.

Before it sends an edit, a payment or hold change or a cancellation, the app checks the order's status in ShipStation. ShipStation doesn't accept changes to orders it has shipped or cancelled, so those changes aren't sent. The status is then Skipped, and Last error gives the order's ShipStation status. Canceling an order that's already cancelled in ShipStation sets the status to Canceled.

When you buy a label, ShipStation notifies the app, and the app reads the shipment from ShipStation with your API keys. It finds the Swell order by its order key, and creates a Swell shipment with the carrier, service, tracking number, ship-to address and the items and quantities in the package. Swell then updates the order's fulfillment status. Shipments come back to the live environment only.

Each order's ShipStation tab shows its Sync status, and the order list has a ShipStation column with the same value.

To send an order again, for example after you fix the cause of an error, open its ShipStation tab, turn on Re-sync on save and save the order. The switch turns itself off when the send is done. Re-sync on save sends the order even if it was never sent, and it shows only while Enable ShipStation sync is on.

ShipStation notifies the app about shipments through two webhooks in your ShipStation account, one for whole orders and one for partial shipments. They're named swell-<store-id>-SHIP_NOTIFY and swell-<store-id>-ITEM_SHIP_NOTIFY. The app registers them when you run setup, and its daily check at 06:00 UTC registers any that are missing and repairs any that point at the wrong address. While Enable ShipStation sync is off, the daily check removes them. These are the live environment's webhooks. The test environment registers none while Callback URL override is empty, and setup and the daily check in one environment never change the other environment's webhooks.

To see your ShipStation stores, their IDs and the webhooks without changing anything, run setup without -X POST:

curl "https://<store-id>.swell.store/functions/shipstation/setup" \
  -u "<store-id>:<secret-key>"

Set ShipStation store ID before the webhooks are registered, because the webhooks are limited to that store when they're created. If you change it later, remove the webhooks as described under Uninstalling, and run setup again.

Settings are in Apps > ShipStation > Settings and are saved separately for each environment.

Send errors are shown in Last error on the order's ShipStation tab, and the ShipStation errors tab in the order list lists the orders whose last send failed. The app also logs each order it sends and each shipment it records or can't record. In the Swell dashboard, the logs are under Developer > Console > Logs.

Check that Enable ShipStation sync is on, that the API keys are set, and that the order is paid, or submitted, as Push orders to ShipStation requires. Orders go to the store in ShipStation store ID, so look in that store. If the status is Error or Skipped, Last error says why. If the order has no status, check the logs. To send the order again, turn on Re-sync on save and save it.

ShipStation didn't accept the API keys. Copy them again from Settings > Account > API Settings in ShipStation. If you regenerated the key, enter both new values.

Add a shipping address to the order, then turn on Re-sync on save and save it.

ShipStation has shipped or cancelled the order, so the edit, payment or hold change, cancellation or re-sync wasn't sent. Make the change in ShipStation.

The order has no physical items, for example only gift cards, so there's nothing to ship.

ShipStation took too long to answer, and Swell sends the order again. If the status stays Error, turn on Re-sync on save and save the order.

Shipments come back to the live environment only. Check that Enable ShipStation sync and Create shipments from ShipStation are on, and run setup to check the webhooks, or with -X POST to repair them. If ShipStation store ID is set, the label must be in that store. The label must be for an order sent from the live environment, by the app or by Swell's built-in integration. A shipment isn't recorded when the order has nothing left to ship in Swell, for example after you added the shipment yourself. The logs show each shipment the app ignored or couldn't record and why.

Neither the ShipStation shipment nor the Swell order has a street address and a 2-letter country code. Add the shipment to the order in Swell yourself.

Enter the API key, API secret and Webhook secret in the app settings, save, and run setup again.

Setup couldn't work out the address ShipStation sends notifications to. Run setup again in the live environment. If the message stays, email support@swell.is.

You ran setup in the test environment, where shipments don't come back. Run setup in the live environment.

Setup or the daily check couldn't tell whether it ran in the test or live environment, so it didn't change any webhooks. Run setup again. If the message stays, email support@swell.is.

Uninstalling the app stops sending orders and recording shipments, and removes the ShipStation tab, the ShipStation column and the ShipStation errors tab from your orders. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.

Swell doesn't tell an app when it's uninstalled, so the app can't remove its webhooks from ShipStation then. Before you uninstall it from the live environment, remove them with setup:

curl -X POST "https://<store-id>.swell.store/functions/shipstation/setup" \
  -u "<store-id>:<secret-key>" -H "Content-Type: application/json" \
  -d '{"action": "remove_webhooks"}'

You can also turn off Enable ShipStation sync in the live environment and uninstall after the next daily check, at 06:00 UTC, which removes them. In the test environment, setup and the daily check remove only that environment's webhooks, never the live environment's.

Orders and shipments in ShipStation stay there, and the Swell shipments the app created stay on your orders. The app's settings and the ShipStation fields on your orders are kept, and come back if you reinstall the app.

The app stores its fields on orders under $app.shipstation: sync_status, order_key, shipstation_order_id, shipstation_order_number, last_synced_at, last_error (up to 500 characters), last_webhook_at, shipments_count, payload_hash (a digest of the last order sent, used to skip updates that change nothing) and resync_requested. On the shipments it creates, it stores shipment_id (the ShipStation shipment ID), batch_number and voided.

Orders are created and replaced with ShipStation's POST /orders/createorder. orderKey is the Swell order ID in live, lineItemKey is the order item ID, advancedOptions.source is Swell and advancedOptions.customField1 is swell: plus the orderKey. An item's unitPrice is its price plus per-unit tax, less the per-unit discount.

The environment comes from req.logParams.environment_id, which is test in the test environment and empty in live. Outside live, orderKey is the environment, a colon and the order ID, such as test:<order-id>, and webhooks are named swell-<store-id>.<environment>-<EVENT> and registered only with a Callback URL override. When the environment can't be read, setup and the daily check don't change any webhooks.

The webhooks point at https://<store-id>.swell.store/functions/<app ObjectId>/shipstation-webhook, because a public call by the app's string ID resolves only with a Swell API key. Setup looks the ObjectId up in /:functions. The address ends with ?secret= and the webhook secret, but Swell passes a POST's body and not its query string, so the secret doesn't arrive on real notifications. The route authenticates a notification by fetching its resource_url itself with your API keys, only from ssapi.shipstation.com or a numbered host such as ssapi12.shipstation.com, only for a /shipments listing, and with includeShipmentItems=True and pageSize=500. A secret that arrives and doesn't match is refused with a 401, and inline shipments under Accept test webhook payloads require it.

Shipments are matched to an order by orderKey when the key belongs to the environment, then by orderNumber without the prefix when the shipment's orderId equals the order's shipstation_order_id, and to items by lineItemKey, then by SKU. A shipment that matches no order is counted as unmatched and acknowledged. Voided labels are handled first and return their quantities, quantities are capped at each item's quantity_deliverable, and shipments already recorded are found by $app.shipstation.shipment_id. The route reads up to 4 pages of 500 shipments per notification. It returns a 503, so ShipStation sends the notification again, when it runs out of time before reading every page or recording every shipment, or when a shipment fails with a transient error.

ShipStation calls time out after 4 seconds, and the status check before an edit or cancellation after 2. A 429 with a Retry-After of 2 seconds or less is waited out once. Timeouts, network errors, 429 and 5xx responses fail the event so Swell retries it. Other errors are recorded on the order and not retried.

To send orders again from the CLI, call resync with an order_id, or with a sync_status to send up to 10 orders with that status. Add --live for the live environment:

swell api post /functions/shipstation/resync --body '{"sync_status": "error"}'

Swell builds and maintains the ShipStation app. For help with the app, email support@swell.is. For questions about your ShipStation account, carriers or labels, contact ShipStation.