What we do
Tools
Industries
Department
How we workLet's talk →
Home/ShipHero
ShipHero

The ShipHero API Runs on Tokens and Credits, Not an API Key

You went looking for an API key in ShipHero and didn't find one, because there isn't one. The ShipHero API is GraphQL, you reach it with a bearer token that belongs to a user, and every query draws from a credit pool the whole account shares. That holds whether you run ShipHero's WMS in your own warehouse or ship through its fulfillment centers.

Where ShipHero stops

Information doesn't leave ShipHero, so someone checks the dashboard to find out what happened.

Stuck on ShipHero? Let's solve it →
Getting access the way ShipHero intends

Create a developer user. In the ShipHero dashboard's user list, add a third-party developer. That user's bearer token and refresh token go to whoever builds the integration, so nobody shares their own login.

Dashboard Users + Add Third-Party Developer

Send queries to one endpoint: https://public-api.shiphero.com/graphql, with the token in an Authorization: Bearer header.

Renew before day 28. Access tokens last 2,419,200 seconds, which is 28 days. POST the refresh token to /auth/refresh on public-api.shiphero.com for a new one. Refreshing doesn't ask for an MFA code.

Where a ShipHero credit pool goes during a busy hour

From ShipHero's docs: 4,004 credits per account by default, restored at 60 a second, shared by every Public API user and token. Each query reserves its estimated complexity up front and refunds whatever it didn't use.

Example burst on a default account
Credits available at the start (One pool for the whole account) 4,004
Orders query, 100 per page, with line items nested inside (Nested connections multiply the cost) − 2,100
Stock lookup for every SKU on a storefront sync − 1,300
A reporting tool someone else connected (Same pool, different token) − 700
Short by 96 credits, so the reporting query is refused with error code 30 −96

Run a query with analyze: true first to see its cost without spending anything, and read extensions.throttling.user_quota on each response for what's left. Separately, the API allows 7,000 requests in any five minutes, and going over that returns a 429.

ShipHero webhooks that stop arriving, and why

Webhooks are registered with the webhook_create mutation, naming the type exactly as ShipHero lists it (Shipment Update, Inventory Change, Order Canceled, Return Update and so on).

The shared secret was never saved

How you'll know: Your listener has no way to check the x-shiphero-hmac-sha256 header.

Fix: shared_signature_secret is shown once, when the webhook is created. Keep it in a secrets store. Then base64 the HMAC of the request body and compare it to the header in constant time.

The endpoint does the work before it answers

How you'll know: Deliveries fail during busy periods even though your server is up.

Fix: ShipHero waits 10 seconds for a 2xx and allows 5 retries per trigger. Acknowledge at once and queue the job. Generate Label is the exception: it gets 20 seconds because it has to send a label back.

The webhook slid to UNHEALTHY

How you'll know: Events stopped and webhook_enable doesn't bring them back.

Fix: Health moves from HEALTHY to WARNING to UNHEALTHY, and at the last stage only a ShipHero representative can switch it back on. Alert on WARNING, and backfill anything missed with a query once the endpoint recovers.

Every page of results pulled in one query

How you'll know: Large order pulls burn the pool in a few calls.

Fix: Connections take first or last (100 at most when neither is set) and page with after and pageInfo.endCursor. Page nested connections in their own queries rather than inside the parent.

ShipHero data that reaches the store, the books and support

Inside ShipHero, stock and order status are accurate. The trouble is everywhere else: a Shopify listing that still shows a unit the packing app just picked, a wholesale invoice nobody sends until someone checks the dashboard, a support agent who has to open ShipHero to answer "has it shipped?". Native store and carrier integrations cover the common cases; accounting, custom reporting and anything off that list need a build against the API.

n-frames builds that layer on the ShipHero API. Inventory Change and Inventory Update webhooks push the new count to the storefronts and marketplaces ShipHero doesn't connect natively, with per-channel allocation rules, so a sale on one channel doesn't oversell on another. Shipment Update raises the invoice in accounting and hands real tracking to the customer and the help desk. Return Update becomes a credit in the books and a closed ticket in support. For the shape of a multi-channel stock setup, see multichannel inventory management, and for comparing fulfillment-side APIs, ShipBob's API.

Writes go through GraphQL mutations; product_create is the example in ShipHero's getting-started guide, and the schema reference lists the rest. Check that the field you need is writable before planning around it.

Questions people ask

What is ShipHero?

Cloud warehouse management software with a barcode-scanning mobile app for picking and packing, for businesses that run their own warehouse. ShipHero also runs its own fulfillment centers, so the same company is both a WMS you operate and a 3PL you can hand fulfillment to.

How much does ShipHero cost?

It depends on whether you use the WMS in your own building or ShipHero's fulfillment network, and either way it scales with order volume. Get a current number from ShipHero, since older published figures go stale.

Does ShipHero offer fulfillment, or is it only software?

Both. The WMS runs in a warehouse you operate. Separately, ShipHero operates fulfillment centers as a 3PL for brands that would rather not run a warehouse at all. The API serves both setups.

Can I request a demo of ShipHero?

Yes. ShipHero books demos through its own site for both the WMS and the fulfillment network.

Is ShipHero a good fit for a growing ecommerce brand?

For a brand that's outgrown spreadsheet stock counts and manual pick-and-pack, it's a reasonable fit, as software or as outsourced fulfillment. Where it needs help is getting warehouse events into accounting, every storefront and the help desk without someone checking the dashboard.

What does ShipHero integrate with natively?

Common storefronts and carriers. Check ShipHero's integrations list first; anything not on it needs a connection written against the ShipHero API, which is the work n-frames does.

Does the ShipHero API use API keys?

No. ShipHero's docs say API keys aren't needed for the public API. You authenticate with a bearer token, ideally from a third-party developer user, and renew it with the refresh token every 28 days.

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.