SKUSavvy API: GraphQL API for Warehouse and Inventory Management

The SKUSavvy API is a GraphQL API with access to everything in your SKUSavvy account: products, variants, bin level inventory, orders, shipments, purchase orders, transfers, pick batches and more. Use it to connect your warehouse to accounting, ERP and reporting tools, automate workflows, or build your own add-on on top of your Shopify WMS.

Authentication with API Tokens

Every API request is authenticated with an API token. Sign in to SKUSavvy and go to Account > API Tokens to create one. The token is shown only once, so store it somewhere safe, such as a secrets manager or an environment variable.

Send the token in the X-Token header on every request. An Authorization: Bearer header also works.

X-Token: <your API token>
# or
Authorization: Bearer <your API token>

Making Your First GraphQL Request

Send a POST request to https://app.skusavvy.com/graphql with a JSON body containing query, and variables when the operation declares $variables. This query reads the user that owns the token:

query Me {
  me {
    id
    name
  }
}

Send it with the fetch built into Node.js 18 and later:

const response = await fetch('https://app.skusavvy.com/graphql', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-token': process.env.SKUSAVVY_API_TOKEN,
  },
  body: JSON.stringify({
    query: 'query Me { me { id name } }',
    variables: {},
  }),
});

const { data, errors, extensions } = await response.json();
console.log(data, errors, extensions);

API Rate Limits

The SKUSavvy API uses a sliding window rate limit based on query complexity, not on the number of requests. Each operation has a cost based on the fields it selects, and the total cost of your operations in the last 60 seconds must stay under the limit.

• Limit: 7,500 complexity points per rolling 60 second window

• All API tokens of a company share one budget

• The window slides: each operation's cost stops counting 60 seconds after it ran, so capacity comes back gradually, not all at once at a fixed reset time

• Operations that go over the limit are rejected and do not run

Reading Your Current Usage

Every response includes extensions.cost: operationCost is the cost of this operation, and currentCost is the total cost of your operations in the current window, this one included.

{
  "extensions": {
    "cost": {
      "operationCost": 12.5,
      "currentCost": 840.25,
      "limit": 7500,
      "windowSeconds": 60
    }
  }
}

Handling a Rate Limit Error

When an operation would go over the limit, the API returns HTTP status 429 and an error with the message "Rate limit exceeded". The error's extensions.cost includes waitTimeInSeconds: the number of seconds until enough earlier operations leave the window for this one to fit. Wait that long, then retry the same request.

{
  "errors": [
    {
      "message": "Rate limit exceeded. ... Please try again in 14 seconds.",
      "extensions": {
        "cost": {
          "operationCost": 310,
          "currentCost": 7350,
          "limit": 7500,
          "windowSeconds": 60,
          "waitTimeInSeconds": 14
        }
      }
    }
  ]
}

Keeping Query Costs Low

• Select only the fields you need: nested objects and lists add to the cost

• Set a limit on list fields: a higher limit costs more

• Free-text search costs much more than a lookup by field, so use it only for searches a person types in

• To find records by a known value, search by field: SKU, barcode or external ID for products and inventory items, name or barcode for bins, and name for vendors

• The field searches (variantSearchBulk, inventoryItemSearchBulk, binSearchBulk and vendorSearchBulk) take up to 100 lookups in one request

• Use webhooks to get notified of changes instead of polling

SKUSavvy API Reference

The full API reference is the GraphiQL explorer. The schema documents itself and is always up to date: browse every query, mutation and subscription, read the field descriptions, and run operations against your own account.