Connect ShipStation (shipping-label costs)

Connecting ShipStation replaces your estimated shipping cost with the real one. Every label you buy carries a carrier charge that MarginOS reads and attributes down to the individual SKUs in that box — so the profit on a heavy, cheap product stops being a guess.

Unlike the ad platforms, this is a single step: paste an API key you generate inside ShipStation. There is no account-selection stage afterwards, and cost starts arriving within seconds of connecting.

Why this one matters more than it looks

Shipping is the cost most often carried as an assumption. Until a real label cost lands, MarginOS uses the store-wide shipping fallback you set during setup — a single number applied to every order, which is honest but blunt. It cannot know that one SKU ships in a padded envelope and another ships freight.

Real label costs change which products look profitable, not merely how precisely you can state it. A product with a healthy margin on a store-wide average can be a loss-maker once its actual postage is counted, and nothing on your dashboard will say so until the measured cost arrives.

Before you start

• Connect Shopify first. A shipping cost needs an order and a SKU to attach to.
• You need a ShipStation plan that exposes the shipping API — Standard or Premium. The Free and Starter tiers do not, and a key from one of those will be refused at connect with that reason spelled out.
• Generate the key in ShipStation under Settings → Account → API Settings. MarginOS never asks for your ShipStation password.
• Connect from your own MarginOS login. When a MarginOS system administrator is viewing your workspace for support, the connect controls are replaced by Admins cannot connect ShipStation — nobody at MarginOS can attach your shipping account on your behalf.

How to connect

1. Open Account Setup, go to the Integrations tab, and click Configure on the ShipStation card.
2. In the panel headed ShipStation (Direct API), paste your key into ShipStation API key.
3. Click Connect ShipStation. The key is validated against ShipStation before anything is saved, so an invalid key or an ineligible plan is refused immediately rather than failing quietly hours later.
4. The panel switches to Connected and a first backfill starts on its own. You do not need to wait on the page.

Your key is encrypted at rest and used read-only. MarginOS never modifies your ShipStation orders, shipments or settings. Once saved, the key is never shown again — the panel displays only its first characters, as Key: abc123••••, which is enough to tell two keys apart and useless to anyone who sees it.

What MarginOS reads from ShipStation

MarginOS reads the money and the merchandise, not your customers. Addresses, names and phone numbers on a ShipStation shipment are never carried into the profit model — the fields taken from each label are chosen explicitly, so customer contact details cannot arrive by accident.

How one label becomes per-SKU cost

A shipping label is bought per box, but profit is measured per product — so a label covering more than one SKU has to be divided. MarginOS splits it by shipping weight, falling back to unit count when weights are missing. A 3 kg item and a 200 g item in the same parcel do not carry the same share of the postage, and splitting evenly would quietly subsidise the heavy product at the light one’s expense.

Four rules keep that division honest:

• Voided labels are ignored — but a genuinely free label is not. A label you bought and cancelled never cost you anything, so it never becomes a cost. A label ShipStation actually billed at $0 is different: that is a measured cost of zero, and MarginOS records it as one. Treating it as missing would push those products back onto your store-wide shipping estimate and quietly overstate their cost.
• A label ShipStation has not priced yet is left alone, not guessed at. Costs that are still settling are picked up on a later sync once a figure appears. If a label is later credited back, the credit is recorded against the same products rather than discarded, so what you see nets out to what you actually paid.
• Non-product lines are excluded before the split, not after. Shopify forwards discounts, loyalty entries and promo names onto a shipment alongside the real items. They have no cost basis, so they are dropped first and the real SKUs carry the full label cost between them.
• A label MarginOS cannot attribute is quarantined, never spread. If a label’s shipment cannot be resolved, or it turns out to contain no real product line at all, the cost is set aside intact in Unmapped Costs with the reason attached. It is not silently smeared across your catalogue and it is not dropped — see why MarginOS would rather show a gap than invent a number. Where the shipment is genuinely gone for good, you can stop MarginOS re-checking it; the cost stays on record either way.

Once attributed, a real label cost counts as measured evidence rather than an assumption, which is what lifts a SKU’s rating in the Defensible Profit Model and its Data Trust level. The number in your margin stops being something you configured and becomes something you can point at.

Where the cost shows up

Open any SKU’s detail drawer from your catalogue. The Logistics Cost / Unit (30d) tile carries the per-unit total, broken into Outbound, Returns and Inbound. Where ShipStation is connected, its tooltip also compares your shipping paths directly — for example, Most expensive path: usps priority $14.20/order vs cheapest usps ground $6.80/order. That single line is often the first time a brand sees that one service level is quietly eating a product’s margin.

The same drawer’s Evidence Ledger lets you expand the individual labels behind the fulfillment figure, so any number can be traced back to the shipments that produced it. Return labels appear separately as return shipping against the return events they belong to, rather than being blended into the outbound cost.

How often costs arrive

The daily sync is the backbone: it runs unattended every day, and it re-reads a recent window rather than only the newest day, so a label bought late or corrected after the fact still lands.

On top of that, MarginOS registers a real-time New shipping label event with ShipStation, listed under Live events on the panel as Registered ✓. When it is active, a new label’s cost arrives in minutes rather than waiting for the next day’s pass.

Occasionally ShipStation cannot give up that real-time slot — most often because another application already holds it. Nothing breaks: the panel says Real-time events aren’t active — costs still sync on the daily schedule, and the daily pass captures everything regardless. Real-time is an accelerator here, never the source of truth.

Sync Now, on the panel, forces an immediate pass when you want a figure refreshed rather than waiting.

Reading the connection panel

The badge at the top reads Connected when healthy, Syncing… while a pass is running, or Attention (data quality) when the connection needs a look. Last successful sync underneath tells you how current the shipping costs behind your margins actually are.

A red 24H Failures badge counts costs that arrived but could not be attributed in the last day. It is a count, not a link — the alert that explains each one reaches you on its own, and names the labels involved.

Labels ShipStation cannot explain

Sometimes ShipStation bills you for a label and then cannot tell MarginOS what shipped on it — usually because the shipment behind it was deleted or archived after the label was bought. Without those lines there is no product to attach the cost to, so it is held aside rather than guessed at.

The panel lists these under Shipping labels we can’t attribute, each with the label reference and the date it was set aside. MarginOS keeps re-checking them on its own, and picks the cost back up if the shipment reappears.

When a label is never coming back, an administrator can stop the chase. Write off on that row asks you to confirm — naming the exact amount first — and then MarginOS stops re-checking it. The cost stays on record; it simply stops waiting to be matched. A running count of what you have set aside this way sits under the list, with View them to see each label, its amount, its date and the reason given.

Two things behave differently from what you might expect, and both are deliberate:

• A credit is treated as the mirror image, not as an error. When a label ends up owing you money rather than costing it, writing it off means that refund is never taken off your product costs — so your costs stay a little higher than reality and your profit reads slightly worse. The confirmation says so in those terms rather than reusing the wording for a charge.
• Writing one off does not silence the alert. It changes what the alert says. Once nothing is left waiting, it turns from a warning into a record of the gap you accepted — because a cost that is permanently missing from your margins is worth knowing about even after you have decided to stop chasing it.

When something needs your attention

Two alerts come from this integration, and they mean very different things.

ShipStation history still mapping is informational and needs nothing from you. A large back catalogue of labels is mapped in bounded passes rather than one enormous run, so a busy store’s first days can end a cycle mid-history. No cost is lost — the next sync resumes exactly where the last one stopped.

ShipStation sync is failing does need you, and quickly. It usually means the API key was rotated or revoked on the ShipStation side, which ShipStation itself has no way of telling us. While it persists, new shipping costs are not reaching your SKU economics — and missing cost does not read as an error on a dashboard, it reads as better margins. Reconnect from the same panel with a fresh key.

Example

A brand ships a 2.4 kg cast-iron pan and a 150 g spice tin together. The label costs $12.60.

Split by weight, the pan carries roughly $11.86 of that label and the tin about $0.74. Split evenly — the naive approach — each would carry $6.30, which would overstate the tin’s shipping cost by more than eight times and flatter the pan.

That distortion is the whole point. At a $9 selling price the spice tin looks marginal under an even split and healthy under a weight-based one, while the pan absorbs a postage bill its price can carry. Before ShipStation was connected, both products carried the same store-wide shipping assumption and neither figure was true.

Common questions

ShipStation rejected my API key.

Two different problems produce that, and the message tells you which. Invalid key means the key itself was not accepted — regenerate it under Settings → Account → API Settings and paste the new one. A plan message means your ShipStation tier does not expose the shipping API at all; Free and Starter do not, so you would need Standard or Premium (or a ShipStation API / ShipEngine plan) before connecting.

Do I still need my store-wide shipping estimate?

Yes, and it stays in place. Real label costs cover the orders that actually shipped through ShipStation; the fallback continues to cover everything else, including history from before you connected. The two coexist — MarginOS uses the measured cost wherever it has one, and says so.

Does this change my inventory numbers?

No. This connection is deliberately cost-only. ShipStation is not treated as the source of truth for stock, so nothing here alters your inventory levels or valuations — it only tells MarginOS what shipping actually cost.

What about return labels?

They are captured too, and kept distinct from outbound postage. Returns cost real money and the cost of getting goods back belongs to the products that came back, not to the ones going out — which is why the SKU drawer reports outbound and returns as separate legs rather than one blended figure.

Why is a cost sitting in Unmapped Costs instead of in my margins?

Because MarginOS could not prove which SKUs it belonged to. The usual cause is a label whose shipment lines are all non-product entries, or a shipment that no longer exists on ShipStation’s side. The cost is preserved with its reason rather than being guessed at — the Unmapped Costs guide covers resolving each reason. For the second cause specifically, the ShipStation panel lets an administrator stop the re-checking once a shipment is clearly never coming back.

What happens if I disconnect?

Your stored key is removed and syncing stops. Costs already attributed to your margins stay exactly as they are, so past periods keep reporting the profit they actually earned. From that point, new labels are not captured — so shipping cost on recent orders reverts to the store-wide assumption, and margins will read better than reality until you reconnect.

Related

• Set your store-wide COGS, shipping and pick-pack fallbacks — what real label costs replace.
• Why a cost landed in Unmapped Costs — resolving a shipping cost that could not be attributed.
• The Defensible Profit Model — why measured costs outrank assumed ones.
• How MarginOS calculates Gross Profit (CM1) — where fulfillment cost lands.
• Connect your Shopify store — the connection this one builds on.