ShipHero API Integration
API Overview
ShipHero provides a GraphQL API for managing e-commerce fulfillment operations.
Endpoints:
Quick Start
Authentication
Get a JWT token (expires in 28 days):
curl -X POST https://public-api.shiphero.com/auth/token
-H "Content-Type: application/json"
-d '{"email": "EMAIL", "password": "PASSWORD"}'
Use the token in all requests:
Authorization: Bearer YOUR_ACCESS_TOKEN
For detailed auth patterns including token refresh: See references/authentication.md
Basic Query Pattern
All queries return request_id , complexity , and data :
query { products { request_id complexity data(first: 25) { pageInfo { hasNextPage endCursor } edges { node { id sku name } } } } }
Core Operations
Orders
Create order
mutation { order_create(data: { order_number: "ORD-123" shop_name: "my-shop" shipping_address: { first_name: "John", last_name: "Doe", address1: "123 Main St", city: "NYC", state: "NY", zip: "10001", country: "US" } line_items: [{ sku: "SKU-001", quantity: 1, price: "29.99", product_name: "Widget" }] }) { order { id order_number } } }
Inventory
Add inventory
mutation { inventory_add(data: { sku: "SKU-001" warehouse_id: "WAREHOUSE_UUID" quantity: 50 reason: "Restocking" }) { warehouse_product { on_hand } } }
For complete operations: See references/graphql-operations.md
Rate Limits & Query Optimization
Credits:
-
Starting: 4,004 credits
-
Restore rate: 60 credits/second
-
Max operation cost: 4,004 credits
-
Hard limit: 7,000 requests per 5 minutes
Optimization tips:
-
Always specify first or last parameter (default 100 is expensive)
-
Use analyze: true to preview query cost before executing
-
Request only needed fields
-
Use filters (created_at_min , updated_at_min ) to narrow results
Preview query cost
query { orders(analyze: true) { complexity # Returns estimated cost without executing } }
Webhooks
Register webhooks for real-time events:
mutation { webhook_create(data: { name: "Shipment Update" # Must match exactly url: "https://your-endpoint.com/webhook" shop_name: "api" }) { webhook { shared_signature_secret } # Save this! } }
Available webhooks: Inventory Update, Inventory Change, Shipment Update, Order Canceled, Order Packed Out, Return Update, PO Update, and more.
For full webhook reference: See references/webhooks.md
3PL Operations
For 3PL accounts managing multiple customers:
Option 1: Use customer's credentials directly
Option 2: Add customer_account_id to requests:
query { orders(customer_account_id: "CUSTOMER_UUID") { data(first: 25) { ... } } }
Converting Legacy IDs
Convert legacy integer IDs to UUIDs:
query { uuid(legacy_id: 12345, entity_type: "order") { uuid } }
Error Handling
Capture request_id from all responses for debugging:
{ orders { request_id # Always include for support data { ... } } }
Common error codes: 3 (Invalid Argument), 5 (Not Found), 16 (Unauthenticated)
Python Client Example
from gql import gql, Client from gql.transport.requests import RequestsHTTPTransport
transport = RequestsHTTPTransport( url="https://public-api.shiphero.com/graphql", headers={"Authorization": f"Bearer {token}"} ) client = Client(transport=transport)
result = client.execute(gql(""" query { products { data(first: 10) { edges { node { sku } } } } } """))
Reference Files
-
references/graphql-operations.md: Complete query/mutation examples for orders, products, inventory, shipments, returns, purchase orders
-
references/webhooks.md: Webhook types, registration, verification, best practices
-
references/authentication.md: Token management, refresh patterns, 3PL auth