What we do
Tools
Industries
Department
How we workLet's talk →
Home/ShipStation/ShipStation API V1 or V2
ShipStation

ShipStation API: Picking V1 or V2 Before You Write the First Call

You open API Settings in ShipStation and it asks which version you want a key for. They aren't one API with a new number. V1 signs in with a key and secret and is built around orders. V2 uses a single API-Key header and is built around shipments and labels. Pick the wrong one and you rewrite later. Here's how they differ, and the jobs neither one does.

A first request, on either version

Keys: choose the version on the API Settings page and generate a key there. A V2 key is shown once, so store it the moment it appears. If your plan doesn't include API access, that page will tell you.

Settings API Settings

V1: Basic auth, with the API key as the username and the secret as the password, sent to https://ssapi.shipstation.com. The limit is 40 requests a minute for each key and secret pair.

V2: the key goes in an API-Key header on every call to https://api.shipstation.com/v2/. A 429 comes back with a Retry-After header giving the seconds to wait.

ShipStation V1 and V2, compared for the job in front of you

V1

Built around orders

  • Create, update and list orders, so a custom store or ERP can push its orders in.
  • Create and void labels, get rates, and work with customers, products, stores and warehouses.
  • Webhooks for new and shipped orders. Each one carries a resource_url you call to fetch the records themselves.
  • 40 requests a minute per key and secret, with rate-limit headers on each response.
V2

Built around shipments and labels

  • Rate shopping, shipments, labels, multi-package labels, batches, return labels, manifests and pickups.
  • Inventory: stock levels by SKU, plus inventory warehouses and locations.
  • Orders aren't fully represented yet. A shipment created with create_sales_order: true shows up in the Orders tab.
  • ShipStation calls V2 an early release, so a few V1 features may be missing.

Pushing orders in from a system ShipStation has no store connection for? V1 still does that most directly. Batch labels, returns or stock levels? V2. Some builds use both, each with its own key.

Why a ShipStation integration falls over in its first busy week

429s during the afternoon label rush

How you'll know: Calls fail in bursts exactly when the warehouse is printing.

Fix: Every process sharing a V1 key draws on the same 40 a minute. Put one queue in front of the API and pace it. On V2, wait the seconds Retry-After gives, and pause the whole queue rather than retrying each request on its own.

The webhook arrives, but the order details don't

How you'll know: Your listener gets a V1 notification with almost nothing in it.

Fix: The notification is a pointer. Call its resource_url with your credentials to fetch the orders or shipments, and count that call against your rate limit.

Nobody saved the V2 key

How you'll know: The integration needs a key and the only copy was in someone's terminal.

Fix: It's displayed once. Generate a new one, keep it in a secrets store, and update every service that used the old one.

Automation rules didn't change

How you'll know: You expected an endpoint to set up or edit a rule.

Fix: Automation rules live in the dashboard. The API reads and writes the orders and shipments those rules act on, so set the values the rule matches on, or apply the logic in your own code before the order arrives.

A V2 build can't list orders

How you'll know: Code ported from V1 has nothing to call for the order list.

Fix: V2 works from shipments. Keep V1 for order sync, or model the job on shipments with create_sales_order if staff still need to see it in the Orders tab.

EDI and the other jobs the API leaves to you

ShipStation doesn't handle EDI natively. When a big-box retailer sends its purchase order as an 850 and wants an 856 advance ship notice before it accepts freight, those documents have to come from outside ShipStation: an EDI provider, a translation layer, or both, reaching ShipStation through its API.

n-frames builds that translation. The retailer's purchase order becomes an order ShipStation can ship, and the shipment ShipStation creates becomes the ship notice the retailer expects, with tracking mapped from the label. The trading-partner requirement stops being a data-entry job.

The same applies to webhook-driven sync: a shipped notice reaching your ERP or accounting system shortly after the label prints, rather than in a nightly export. And where a job depends on settings that only exist in the dashboard, such as automation rules at scale, scripted browser automation against the dashboard is sometimes more dependable than forcing an API that was never built for it. Store-specific setups are covered on the ShipStation and Shopify page.

Let's talk

A ShipStation build that holds up at peak

n-frames writes ShipStation integrations on the version that fits the job, paces every call through one queue, and adds the EDI layer when a retailer requires it. We host it and watch it, so a failed push shows up as an alert rather than a missing shipment.

Book a build review →

Questions people ask

Does ShipStation have an API?

Yes, two of them. V1 is the older REST API, built around orders, with Basic auth. V2 is newer, built around shipments, labels and inventory, and authenticates with an API-Key header. Both are separate from the dashboard your team ships from.

How do I get a ShipStation API key?

In ShipStation, go to Settings, then API Settings, choose V1 or V2 and generate the key. V1 gives you a key and a secret. A V2 key is shown only once, so save it straight away. The same page tells you if your plan doesn't include API access.

Does the ShipStation API support webhooks?

Yes. V1 webhooks fire on events such as a new order or a shipment going out, and send a resource_url you call to fetch the details. V2 has its own webhooks, so check its event list before porting a V1 listener across.

Can I manage ShipStation's automation rules through the API?

Not directly. Rules are set up in the dashboard. The API reads and writes the orders and shipments those rules act on, so integrations usually set the fields a rule matches on instead.

Does ShipStation support EDI?

Not natively. If a trading partner requires EDI documents such as an 850 purchase order or an 856 ship notice, you need an EDI provider or a custom translation layer that talks to ShipStation through its API. n-frames builds that layer.

What is the ShipStation API rate limit?

On V1 it's 40 requests a minute for each key and secret pair, and going over returns a 429. V2's rate-limit guide gives its own default and sends a Retry-After header with each 429. Either way, retry from one shared queue, not from each request.

Should a new ShipStation integration use V1 or V2?

Use V2 for labels, batches, returns, rates and inventory. Use V1 when you need to create and list orders, since V2 doesn't fully expose them yet. If you need both, run them side by side with a key for each. ShipStation's own docs recommend V2 wherever possible and maintain V1 for existing integrations, so write a V1 order sync so it can move to V2 later.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.