ShipHero API Integration

API Overview

ShipHero provides a GraphQL API for managing e-commerce fulfillment operations.

Endpoints:

GraphQL: https://public-api.shiphero.com/graphql
Auth: https://public-api.shiphero.com/auth/token

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

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

ship-hero