Integrating ShipHero (Inventory)
Auth: OAuth 2.0 · Partner program: not required · Setup time: about 20 minutes · Last verified: 2026-05-23
ShipHero is a warehouse + fulfillment platform with a public GraphQL API. The adapter wraps ShipHero’s Inventory queries + mutations and surfaces products, warehouses, bins, on-hand inventory, and inventory transactions into the canonical inventory schema.
Auth model
Section titled “Auth model”- ShipHero exposes an OAuth-style refresh-token flow built on top of username + password authentication, not a hosted authorization-code redirect:
POST https://public-api.shiphero.com/auth/tokenwithusername,password→ returnsaccess_token(JWT bearer, ~28-day TTL) andrefresh_token.POST https://public-api.shiphero.com/auth/refreshwith the refresh token → new access token.
- Scope string in the response is
openid profile offline_access. - All API calls hit
POST https://public-api.shiphero.com/graphqlwithAuthorization: Bearer <token>. - There is no hosted consent screen; the connecting user supplies their ShipHero credentials directly to your integration. Plan UX (and trust) accordingly.
Prerequisites
Section titled “Prerequisites”- A ShipHero account at shiphero.com.
- A dedicated API user in the ShipHero account (Settings → User Accounts). Never reuse a human’s credentials — create a service user, assign warehouse + inventory roles only, store its credentials.
Configure in admin
Section titled “Configure in admin”- Open
/platformsin the admin UI, filter to Inventory, click ShipHero. - Fill Configure:
username— the ShipHero API user’s email.password— the ShipHero API user’s password.
- Enable the adapter. The adapter exchanges these for the JWT pair and stores the refresh token; the password is not retained after the first exchange.
Required scopes
Section titled “Required scopes”ShipHero does not expose per-scope OAuth grants. The effective permissions come from the role assigned to the API user in ShipHero. Lock that role down to Inventory + Warehouse + Products only.
Webhooks
Section titled “Webhooks”ShipHero delivers JSON webhooks for inventory + shipment events. Configure under Settings → Webhooks (or via the GraphQL webhook_create mutation). Subscribe to:
Inventory UpdateInventory Change(per-warehouse on-hand deltas)PO UpdateShipment Update(for outbound impact on on-hand)
Webhook signature semantics are not formally documented; the adapter expects an HMAC-SHA256 in the x-shiphero-hmac-sha256 header (base64) when you configure a shared secret. Confirm the exact header with ShipHero support if HMAC verification fails.
Quirks worth knowing
Section titled “Quirks worth knowing”- Username + password exchange, not OAuth Auth Code. Treat ShipHero credentials with the same care as a service-account password — there is no hosted consent.
- Always use a dedicated API user. Re-using a real employee’s account leaks all of their permissions and breaks when they offboard.
- GraphQL throttling is cost-based. Each query costs a number of points; the API returns
complexity+remainingin the response — the adapter back-pressures on these. - Refresh proactively. Access tokens are long-lived (~28 days) but refreshing weekly avoids cliff-edge auth errors during long sync jobs.
References
Section titled “References”opensteward.dev ·Plans and free license ·Terms ·Privacy ·support@opensteward.dev
© 2026 Falco Consulting AB. Built from open-steward/opensteward@a3961d8. This site sets no cookies, runs no analytics and loads nothing from other sites, except platform logos from Brandfetch on the Platforms page.