📘 Sutton Tip: To enable Sutton API access for your account, contact your Customer Success Manager or reach out to us at [email protected].

For custom needs, like connecting Sutton to niche tools, internal systems, or automating specialized workflows, Sutton offers an open API. Use it to:

Read and write data (items, orders, inventory, customers, and more)
Automate repetitive tasks, like syncing orders from custom apps, pushing inventory adjustments, or triggering actions on status changes
Build middleware or automations using platforms like Make.com, Zapier, or custom scripts

Generate an API token

Video walkthrough: Generating API tokens in Sutton: A Step-by-Step Guide

This video shows how to name a token, set its expiry and permissions, and save its value securely.

Create a Token

Every request to the Sutton API, including the API Explorer, uses a token. The token decides which account you are working in and what you are allowed to do.

Go to Settings in the left sidebar, then click API Tokens. This view has the token generator and a table of every token generated for this account.
Give the token a Name that reflects what you will use it for.
Set the token expiry. Choose a preset like 30 days, 90 days, or 1 year, or click the calendar icon to pick a custom date.
Click into Permissions and choose what the token can do. There are three categories: Read, Create and update, and Delete.
1. Click Select all at the top to select every permission.
2. Click Select all within a category to select only that category's permissions
3. Either way, you will see a confirmation prompt before it applies.
Click Generate token.
Copy the token value that appears below the permissions section and save it somewhere secure, like a password manager, before you leave the page.

✅ Best practice: Start with only the permissions you need. A read-only token is a safe way to explore the API without changing any data.

⚠️ Heads up: Once a token is generated, its permissions are locked, and its full value is shown only once. For security reasons, you can't edit the permissions or view the value again from the tokens table. If you lose a token or need different permissions, revoke it and generate a new one.

API Explorer

Video walkthrough: Getting Started with the Sutton API Explorer

This video shows how to sign in to the API Explorer, build a query that reads data, and run a mutation that creates an item.

Open the Explorer

The API Explorer is an interactive tool where you can browse the API documentation, build requests, and see the results. You need a valid API token to open it.

Go to api.heysutton.com.
Enter the API token you generated.
Click Continue to open the Explorer. Your token is added to every request, so you don't need to set up headers.

⛔ Warning: Everything here runs against your live organization. Query results come from real data, and mutations make real changes. If you do not want a query or mutation to touch real records, use a dummy customer or item instead.

Get to know the Explorer

The Explorer has three main panels:

Documentation panel: Lists everything you can request from the API. Use the plus icon next to a field to add it to your operation. A checkmark shows which fields are already part of your current operation.
Operation panel: Shows the request being built as you add fields. The Variables panel below it is where you enter the values your request uses.
Response panel: Shows the data returned after you run the operation.

The documentation starts with two root types: Query for reading data, and Mutation for changing it.

Click any field to see its details. Every field lists its subfields, and some also have arguments you can use to filter results.

To start fresh, click the plus icon next to your open tabs to open a new workspace.

💡 Pro Tip: For a single, complete view of everything the API offers, click Schema in the left sidebar. Most users stay in the default Development view, but the schema is useful if you're comfortable reading GraphQL definitions.

⛔ Warning: You may also notice a SANDBOX label in the corner of this tool. That label belongs to the Explorer tool itself and has nothing to do with your Sutton account; it does not mean your data is safe from changes.

Build a query

Sutton’s API follows standard GraphQL conventions. A query reads data without changing anything. Every query follows the same pattern, whatever data you are looking for:

Open a new workspace.
In the documentation panel, under Query, find the field for the data you want, such as companies, items, or sales orders, and click the plus icon to add it.
Add any arguments you want to filter by. Arguments narrow down which records come back, for example, searching by name.
If the field returns a list, add nodes. The results of a list live inside nodes.
Select the fields you want returned for each record.
In the Variables panel, enter the values for your arguments.
Click the run button at the top right of the operation panel. The results appear in the response panel.

Example: Search companies by name

To find every company with "best" in its name, add companies, add the searchName argument, add nodes, and select name, website, and status. Then set searchName to "best" in the Variables panel and run the query.

The finished query looks like this:

query Companies($searchName: String) {
  companies(searchName: $searchName) {
    nodes {
      name
      website
      status
    }
  }
}

Variables:

{
  "searchName": "best"
}

Build a mutation

A mutation creates, updates, or deletes data in your account. Mutations follow a similar pattern to queries, with two key differences: they often need IDs from other records, and the details you're writing go in the Variables panel.

Find any IDs the mutation needs. For example, creating an item needs a unit of measure ID, and updating or deleting a record needs that record's ID. Run a query in a separate workspace to look them up, then copy the IDs.
Open a new workspace, go back to the Root of the Documentation panel, and click the + icon next to Mutation.
Find the mutation you want, such as one that starts with create, update, or delete, and add it to the operation.
Select the fields you want back in the response. Most mutations return a response wrapper, so click the + icon next to the record field inside it, such as item, to add it to the operation. This reveals the record's fields.
In the Variables panel, replace each null value with the details the mutation needs, including any IDs you copied. Use the Documentation panel to check which fields each variable accepts and which are required.
Click the Run button at the top right of the Operation panel. The Response panel returns the fields you selected, or an error explaining what needs to be fixed.
Confirm the change in Sutton by finding the record on its page. Some records, like items, are saved as drafts when created through the API, so check the All or Draft tab if you don't see them right away.

Example: Create an item

To create an item, first look up a unit of measure ID: run a query on uoms with connection set to first: 50, select id and symbol under nodes, and copy the ID you want. Then add the createItem mutation, expand item to choose the fields you want back, and enter the item details in the Variables panel.

The finished mutation looks like this:

mutation Mutation($input: CreateItemInput!) {
  createItem(input: $input) {
    item {
      name
      sku
      trackingMethod
      defaultStockUom {
        id
      }
    }
  }
}

Variables:

{
  "input": {
    "name": "Item Test",
    "sku": "SKU-1234",
    "trackingMethod":"standard",
    "defaultStockUomId": "018fd014-0db2-77c7-805b-2143bb1e0e0c"
  }
}

⚠️ Heads up: If you leave out trackingMethod, the item defaults to serialized. To learn which method fits your item, see When to Use Standard vs Serialized Inventory Tracking.

💡 Pro Tip: Install the GraphQL Network Inspector browser extension, then open your browser’s developer console in your Sutton account. Watch the requests Sutton makes when you query for data or send mutations to see how everything fits together.

Let your AI assistant build it for you

Building queries by hand is the best way to understand how the API works, but you do not have to write every one yourself. If you connect your AI assistant to Sutton using MCP, it can see your account’s data and help you build, explain, and troubleshoot API requests in plain language.

📘 Sutton Tip: To set up the connection, follow Connect Sutton to Your AI Assistant Using MCP Connectors. To enable Sutton MCP for your account, contact your Customer Success Manager or reach out to us at [email protected].

Once connected, try asking your AI assistant things like:

"Write a GraphQL query for the Sutton API that returns all open sales orders from this week, with the customer name and total."
"I want to update an item’s name through the Sutton API. Which mutation do I use, and what do I put in the variables?"
"My createItem mutation returned an error. Here it is. What is missing?"
"Explain the difference between a query and a mutation, and when I would use each one."

Copy the query your assistant generates into the API Explorer, check it, and run it.

✅ Best practice: Always review an AI-generated query or mutation before you run it, especially a mutation. Run queries first to confirm you are working with the right records, then run the mutation.

ℹ️ Note: Your AI assistant can also read and update your Sutton data directly through MCP, without the API Explorer. The API is the better fit when you are building an integration or automation that needs to run on its own.

FAQ

Where are the API settings?

Go to Settings > API Tokens. API access is not turned on by default, so if you do not see API Tokens, contact your Customer Success Manager to have it enabled.

How technical do I need to be to use the API?

It depends on what you want to do. From least to most technical, your options are: pre-built app integrations, connecting an AI assistant with MCP, webhooks for real-time event notifications, and building directly on the API. The API offers the most flexibility and is best suited to developers or teams with technical support.

Where did my token go?

For security reasons, a token’s full value is only shown once, right after it is generated. If you lost it, revoke it from the tokens table and generate a new one. We recommend saving tokens in a password manager.

Can I change a token’s permissions?

No. Permissions are locked once a token is generated. Generate a new token with the permissions you need, then revoke the old one if you no longer use it.

Why was my mutation blocked?

Your token doesn't have the permission that mutation needs. For example, a read-only token can't create or update records. Generate a new token with Create and Update or Delete permissions, log out of the Explorer, and sign in with the new token.

Why did my query only return some of my records?

List queries return the first 10 results by default. To get more, add the connection argument and set first to a higher number. If you have more records than fit in one page, add pageInfo to your query: when hasNextPage is true, pass its endCursor value as after to get the next page. You can also narrow your results with arguments, such as searchName. Any field that returns a Connection type accepts the connection argument.

Why am I getting an error about a required field or a null value?

A required input is missing from the Variables panel, often an ID. Check the mutation's input in the Documentation panel to see which fields are required, then look up any missing IDs with a query. Some fields are only required in certain cases, such as a unit of measure for standard and serialized items. If the documentation doesn't mark a field as required, check the error message, which names the missing field.

My query returned nothing. What should I check?

If nodes come back empty, your arguments didn't match any records. Check for typos in your variables, try a broader search, and make sure you're signed in with a token from the right account.

My changes appeared in the wrong account. What happened?

The Explorer always works in the account your token was generated in. Click the log out icon at the top right, next to your username, and sign in with a token from the account you want to change.

Will the API Explorer change my real data?

Yes. The Explorer is connected to the account your token was generated in. Queries only read data, but mutations make real changes. We recommend using a token from a sandbox or test account while experimenting.

Is there an API rate limit?

Yes. Sutton's API rate limit is 60 requests per minute.

You’re ready to build with the Sutton API

You now know how to generate a token, build any query or mutation in the API Explorer, and use your AI assistant to speed things up. From here, you can start reading and writing data, automating workflows, and building custom integrations on top of Sutton.

If you have additional questions, please reach out to your Customer Success Manager or contact us at [email protected].

Getting Started with Sutton API