This Claude skill provides expert technical guidance and code patterns for integrating with the ShipHero GraphQL API. It simplifies complex e-commerce operations including order fulfillment, real-time inventory synchronization, shipment tracking, and multi-tenant 3PL management, while ensuring optimal API performance through query cost management and webhook implementation.

When should I use ship-hero?

ship-hero is useful in the following scenarios: • Automating Order Management: Seamlessly create, update, and cancel orders via GraphQL mutations to synchronize external sales channels with ShipHero. • Real-time Inventory Synchronization: Monitor and adjust inventory levels across multiple warehouses to prevent overselling and maintain stock accuracy. • Automated Fulfillment Tracking: Implement webhooks and shipment queries to provide customers with real-time tracking updates and automated status notifications. • 3PL Multi-tenant Operations: Configure and manage multiple client accounts within a single 3PL environment using specific customer account identifiers and legacy ID conversions. • API Performance Optimization: Utilize query complexity analysis and efficient pagination strategies to stay within rate limits and reduce integration latency.

name	ship-hero
description	Expert guidance for integrating with ShipHero's GraphQL API for fulfillment, inventory, orders, and returns management. Use when (1) authenticating with ShipHero API, (2) managing orders (create, update, cancel, query), (3) managing products and inventory levels, (4) creating and tracking shipments, (5) processing returns, (6) working with purchase orders, (7) setting up webhooks for real-time events, (8) implementing 3PL multi-tenant operations, or (9) optimizing GraphQL query costs and pagination.

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

When & Why to Use This Skill

Use Cases