What Can an AI Support Agent Do in ShipStation? Order Status, Holds and Label Voids Through the API (2026)

What can an AI support agent do in ShipStation today?

Five jobs cover most ShipStation-related tickets. The table maps each one to the endpoint ShipStation documents, in the version that supports it, and to who can do it now. "Macha custom tool" means a tool Macha's team configures during onboarding; everything in that column is documented by ShipStation, and only the 401 tests described below were run live.

Two other V1 writes exist that a support agent shouldn't touch. DELETE /orders/{orderId} is a soft delete that "removes order from ShipStation's UI" while keeping it in the database (Delete order), and "create label for order" buys postage. V2 adds shipment tags and internal notes, which are safe for an agent to write because they change nothing the carrier sees.

ShipStation is the most reviewed of the shipping and protection apps we checked for this bundle, ahead of Route and ShipBob. Its Shopify App Store listing showed 4.2 stars from 707 reviews on 28 September 2026 and lists "Shipping API" under the Standard plan (Shopify App Store).

Which ShipStation API version should an agent use, V1 or V2?

The version decides the credentials, the rate limit and which support actions exist. ShipStation's authentication page says the platform issues keys for two APIs from the same API Settings page:

Sources: V1 requirements, rate limits, V2 getting started.

V1 is where the support-friendly calls live. Its orders carry the seven statuses a support agent reasons about (awaiting_payment, awaiting_shipment, pending_fulfillment, shipped, on_hold, cancelled, rejected_fulfillment), and it has the only documented hold and restore calls. It's also the version the incumbents use: Gorgias's setup guide tells merchants to pick "V1 API" and generate a key and secret. V2 has the cleaner label model and the higher rate limit, and its void call puts the label ID in the URL, which makes it the easier write to build as a custom tool. In practice, a support setup today uses V1 for order lookups and holds and V2 for voids, and plans for V1's removal.

The plan gate applies to both. ShipStation's pricing page marks "API access" as not included on Starter and included on Standard and Premium. At the 50-shipment tier on monthly billing that's $14.99 for Starter, $29.99 for Standard and $349.99 for Premium, so the cheapest plan with API access costs $15 a month more than the cheapest plan overall. ShipStation's docs also show the gate per endpoint: each V2 reference page carries an "Endpoint access" block that greys out the plans without access (Products and Plans), and V2's Getting Started page tells platform customers to check their API Settings page "to see if your plan supports API access".

Two more differences catch teams out. ShipStation platform accounts have no sandbox: the docs say "All V2 API operations occur in production and may incur real costs", and suggest voiding test labels immediately. And V2 errors name ShipEngine as the source ("error_source": "shipengine"), because V2 runs on what used to be ShipEngine, so don't read that as a wrong URL.

How does the lookup work, from a ticket to a ShipStation order?

A customer writes in with an email address and usually an order number. ShipStation's APIs don't search by customer email: V1's List orders filters by orderNumber, customerName, dates, status, store and item keyword, and V2's List shipments filters by shipment_number, ship_to_name, sales_order_id and dates (List orders; List shipments). So the identity check belongs in Shopify, and the chain looks like this:

1. Order number from the ticket. Strip the #. On Shopify, Macha's built-in Shopify connector reads the order with Get Order, and its email is what you compare with the requester's before sharing anything.
2. ShipStation order. V1 GET /orders?orderNumber=1096. ShipStation's reference says this filter "performs a 'starts with' search", so 109 also matches 1096 and 1097. The agent must keep only the result whose orderNumber equals the number exactly.
3. Shipments and tracking. V1 GET /shipments?orderNumber= returns each shipment's trackingNumber and whether it was voided. In V2, GET /v2/labels?shipment_id= finds the label and GET /v2/labels/{label_id}/track returns tracking.

V2 has a naming trap. sales_order_id is ShipStation's own identifier for the imported order, not the number your customer quotes, and shipment_number is described as "the user or order source defined shipment number" (other V2 pages label it the order number), so check one real record before relying on it. Our first ShipStation tool for this bundle filtered on sales_order_id=1097; on rereading the reference, we rebuilt it on shipment_number. Without a real account we couldn't confirm that a Shopify-imported shipment carries "1097" there, so check one real record before you rely on either field.

Gorgias's own guide gives the reason to ask ShipStation at all when Shopify already has the order: ShipStation "may have more up-to-date fulfillment info than is available in Shopify." A label printed ten minutes ago shows in ShipStation before the fulfillment syncs back.

What do Gorgias and ShipStation's own Zendesk app already do?

Gorgias AI Agent. Gorgias documents three ShipStation actions its AI Agent can run (Gorgias docs): Get order info, for "where is my order?" questions; Update shipping address, which confirms the new address with the shopper and updates it "so long as orderStatus in ShipStation is not shipped or cancelled"; and Cancel order, under the same status condition. The setup uses a V1 key and secret generated by a ShipStation admin, and Gorgias's steps say to set the key's expiration to 12 months. One detail worth copying into any agent's rules: Gorgias notes that for the shopper to get a refund on a canceled order, the AI Agent "must also use Cancel Shopify order". Canceling in ShipStation stops the shipment; it doesn't refund anyone.

If you're on Gorgias with AI Agent, that covers the address-change and cancel tickets this page is about, and it's the first thing to switch on.

Zendesk. ShipStation publishes a free Zendesk app, "Track orders in Zendesk with ShipStation", that lets a human agent "pull, search, and view recent order data in Zendesk" from the ticket sidebar, set up with a ShipStation API key and secret (Zendesk Marketplace). It displays data; it doesn't reply, hold or void. Zendesk's public marketplace feed, read on 28 September 2026, showed 335 installs, 7 ratings averaging 2 out of 5, and a last app version from July 2018.

ShipStation earns from shipments and label volume, so its own integration effort goes into stores and carriers, and a help-desk sidebar that lets support read an order is enough to keep a merchant from leaving. Gorgias bills per automated resolution, so it earns more the more of these tickets its AI Agent closes, and it built the three actions that close them. Nobody has a reason to build the ShipStation step into an agent on Zendesk or another desk, which is where a custom tool comes in.

Which ShipStation actions should stay with a person?

ShipStation documents more writes than an agent should run unsupervised. The reasons are specific to each action:

• Voiding a label can't be undone. ShipStation's Void Labels guide says it plainly: "Labels Cannot Be Un-Voided!" The carrier also has to support voids and the label must be inside the carrier's window. For ShipStation's own carrier accounts, that's 28 days for USPS and 30 days for UPS and other carriers, and a voided label only earns a refund if it was never scanned.
• Voiding changes the refund path for USPS. Unused USPS labels bought through Stamps.com wallet carriers get ShipStation's Refund Assist, which refunds 70% of the USPS-approved amount as account credit after 21 days. The same guide says labels "manually voided through this endpoint are not eligible for Refund Assist". That's a finance decision, not a support reply.
• An address change on V1 rewrites the whole order. V1's Create or update order "does not currently support partial updates. The entire resource must be provided", and only open orders (awaiting_payment, awaiting_shipment, on_hold) can be updated (Create or update order). An agent that drops the items array while changing a street name edits the order. V2's Update a shipment has a similar shape, and ShipStation's own docs warn that "nulling out the items on a Shipment may cause issues".
• Canceling needs a second system. A canceled ShipStation shipment isn't a refunded Shopify order, as Gorgias's note shows. V2's cancel also requires any label to be voided first.

What's safe to automate is narrower: reads, a V2 tag or internal note on the shipment, and arguably a hold. V1's Hold order until moves an order to On Hold until a date, when it "will automatically change to Awaiting Shipment" (Hold order until). A hold buys a person time to edit the address and costs nothing if nobody touches it, since the order releases itself. If you let an agent hold orders, give it a fixed short date, one or two business days out, in the instruction.

How is ShipStation set up as a Macha tool, and what goes wrong?

ShipStation has no built-in Macha connector. It connects through a custom API tool that Macha's team sets up during onboarding, and custom tools are included on every plan. Macha's custom tools support both auth styles ShipStation needs: Basic Auth for V1, with the API key as username and the secret as password, and API Key auth with a named header for V2.

We built three ShipStation tools on our Macha Demo test org on 28 September 2026, each with a placeholder credential, and pressed Run Test on each:

• "T4-166 ShipStation v1: Find order by number": GET https://ssapi.shipstation.com/orders?orderNumber={{order_number}}, Basic Auth, Read. Test with 1097 returned HTTP 401 with the body 401 Unauthorized.
• "T4-166 ShipStation v2: Find shipment by order number": GET https://api.shipstation.com/v2/shipments?shipment_number={{order_number}}, API-Key header, Read. Test with 1096 returned 401 "Access denied.", and ShipStation's error echoed the path it received, /v2/shipments?shipment_number=1096.
• "T4-166 ShipStation v2: Void label": PUT https://api.shipstation.com/v2/labels/{{label_id}}/void, API-Key header, marked Write. Test with a made-up label ID, se-000000, returned 401 with the path /v2/labels/se-000000/void.

Those 401s are the expected result of fake credentials. They show that each request reached ShipStation's live API with the right auth shape and, for V2, that the parameter landed in the path. They don't show a successful response or a real void, because we have no ShipStation account with API access.

We built the void tool with no body template on purpose. In Macha's current custom-tool runner, a tool with a body template fills its placeholders into the body and doesn't substitute them into the URL. V2's void and cancel calls need no body at all, so the ID in the path fills correctly. V1's writes are the opposite: void, hold and restore each take a numeric orderId or shipmentId in a JSON body. Those need a body template, and Macha's team tests one with a real key against a real order before any agent can use it. V1's full-order address update isn't a good fit for a template tool at all, because the whole order has to be rebuilt from the lookup; route those tickets to a person, or to Gorgias's action if you're on Gorgias.

What goes wrong, in the order we'd expect to hit it:

• The plan. No API access on Starter, so there's no key to paste until the account is on Standard.
• Key expiry. V1 keys are generated with an expiration; Gorgias's guide sets 12 months. When it lapses, every call returns 401, which is exactly the failure our test agents were built to handle. Put the expiry date in your team calendar.
• One V2 key. An account can have one V2 key active at a time, so generating a new one for a support tool can break whatever else used the old one.
• Rate limits. V1's 40 requests a minute is per key and secret. An agent that runs an order lookup and a shipment lookup per ticket uses 2 calls, so 40 ÷ 2 = 20 tickets a minute. That's plenty for support, unless a nightly sync shares the same key; ShipStation allows two V1 key sets, so give the agent its own. V2's 200 a minute gives the same two-call pattern room for about 100 tickets a minute.
• Starts-with matches. orderNumber=109 also returns 1096 and 1097, so the instruction must keep only the exact match.
• Custom Write tools and confirmation. Macha marks a tool like the void as Write. In our dashboard tests a built-in Zendesk write paused for a confirmation card and a custom Write tool didn't, and on trigger runs Write tools run directly when the instruction says so. Don't rely on a card: keep the void tool off customer-facing agents, and put the rule in the instruction.

What happened when we ran a ShipStation agent on test tickets?

We ran two agents through Macha's agent Test feature, which creates a real ticket in our d3v-macha Zendesk sandbox and dispatches the agent the way a ticket-created trigger would. Two artifacts of that feature show in the screenshots: the customer's message appears as an internal comment, and the ticket says "Via API". The agent posts as "Team Ride", the sandbox's admin user (Ride is our made-up demo brand). Our Shopify connector points at Macha's development store, where orders #1096 and #1097 are both paid and unfulfilled. Customers, emails and addresses are made up.

First run, ticket #1124. An earlier agent, "ShipStation label status", had Shopify Get Order and a V2 shipments tool with a placeholder key. A made-up customer asked to change order #1097's address to 22 Harbor Street, Portland, ME 04101. The agent read Shopify (paid, unfulfilled), got a 401 "Access denied." from ShipStation, replied publicly that a teammate was checking the address update and would follow up today, and tagged the ticket app_tool_error and shipping_ai. It changed nothing. It also copied the order's full current shipping address into its internal note, which we masked in the screenshot. Internal notes are read by the whole team and sometimes by other apps, so that's more personal data than the note needed.

Second run, ticket #1151. For this page we built "T4-166 ShipStation address change (safe mode)" with the instruction below, Shopify Get Order, Zendesk read, reply, note and tag tools, and the V1 lookup tool. It has no ShipStation Write tool. The instruction adds an identity check and forbids copying the order's address into notes. A made-up customer, Dana Whitfield, wrote from [email protected]: "Can you send order #1096 to my new address instead? 48 Alder Lane, Apt 3, Burlington, VT 05401."

1. The agent read the ticket, then called Shopify Get Order and the ShipStation V1 lookup in parallel.
2. Shopify returned #1096 as paid and unfulfilled, under an email that isn't Dana's. ShipStation returned HTTP 401, 401 Unauthorized.
3. The email check won. The public reply, 18 seconds after the ticket was created, asked Dana to write from the email used to place the order and shared no order details.
4. The internal note recorded the mismatch, the ShipStation tool, the 401 and the requested new address as Dana wrote it. It didn't copy the order's current address, name or email.
5. It tagged the ticket app_tool_error, and not address_change, because nothing was passed on.

That's the behavior we wanted, and it's the most common way this setup meets real customers: a shopper writing from a work address, a partner's account or a typo. The run doesn't prove the happy path. We never saw ShipStation return an order, so the status branches in the instruction are built from ShipStation's documentation, not observed. Two runs on made-up tickets are also far too few to call the agent reliable; they show the failure handling works, which is the part you can test without a live key.

Here's the instruction from the second run, written for acting:

When a customer asks to change the shipping address on an order, or asks whether it has shipped: get the ticket and the requester's email, and take the order number from the message, digits only, without the # sign. Call Shopify Get Order, then call "T4-166 ShipStation v1: Find order by number" and keep only the result whose orderNumber equals the number exactly, because ShipStation matches the start of the number. If the Shopify order's email doesn't match the requester's, don't share any order details and don't pass the change on: ask them to reply from the email they ordered with, add an internal note saying the emails don't match, and stop. If orderStatus is shipped, tell them it has already shipped and that a teammate will check whether the carrier can redirect it. If orderStatus is awaiting_payment, awaiting_shipment or on_hold, don't change anything yourself: reply that a teammate will update the address before the order ships and confirm by email, add an internal note with the order number, the ShipStation orderId and orderStatus, and the new address exactly as the customer wrote it, and tag the ticket address_change. If orderStatus is cancelled, say the order was canceled and that a teammate will follow up. Never copy the order's current shipping address, or the customer's name and email from the order, into a note or a reply; call it "the address on the order". If any ShipStation tool returns an error, don't tell the customer what failed inside our systems: reply that a teammate is checking and will follow up today, add an internal note with the tool name, the HTTP status, the error message and the requested new address, and tag the ticket app_tool_error.

If you add a hold tool later, the natural place is the awaiting_shipment branch: hold the order for one business day, say so in the note, and let the teammate release it after editing the address.

Where Macha fits with ShipStation

Macha fits teams on Zendesk, Freshdesk, Gorgias, Front, HubSpot or Intercom whose shipping questions arrive in the help desk and need an answer that checks the Shopify order, reads ShipStation's status and leaves a note a teammate can act on, especially teams not on Gorgias AI Agent, where the three ShipStation actions already exist. Macha's built-in Shopify connector reads the order and checks the requester's email. ShipStation connects through custom API tools that Macha's team sets up during onboarding, with V1 Basic auth for order lookups and holds and a V2 API-Key header for label calls, on a ShipStation plan that includes API access. The agent replies, tags and writes internal notes through the help desk connector, and it leaves voids, cancellations and address edits to your team unless you decide otherwise. See Macha on Zendesk for how the agent sits on a help desk. Macha is the done-for-you option here. You connect your help desk and Shopify, about 15 minutes, and hand over a ShipStation key from a plan with API access. The Macha team then analyzes about a month of your past tickets, builds the ShipStation tools and the agent, tests it on a sample of those tickets, and runs it in safe mode, with drafts as internal notes in your help desk, until the drafts are right. Gorgias AI Agent's ShipStation actions and ShipStation's Zendesk app are set up by your own team, following each vendor's guide. Macha starts at $299/month for 750 tickets, about $0.40 per ticket, and that includes the setup and a dedicated success manager who handles your changes after go-live, such as a renewed V1 key, a new tool or an instruction edit.

ShipStation is one of several shipping apps an agent may need. The shipping, protection and fulfillment hub compares ShipStation with ShipBob and Route on address changes and claims, and the Route page covers why a package-protection claim can't be filed through Route's API. For tracking questions after the label is printed, see order-tracking apps for WISMO and the AfterShip page. For the full map of Shopify apps, see which Shopify apps an AI support agent can work with.

Frequently asked questions

Does the ShipStation API cost extra? There's no separate API fee on the ShipStation platform, but API access depends on the plan. ShipStation's pricing page marks API access as not included on Starter ($14.99 a month at 50 shipments) and included on Standard ($29.99) and Premium ($349.99). ShipStation API, formerly ShipEngine, is a separate developer product with its own plans.

What's the difference between the ShipStation V1 and V2 APIs? V1 uses Basic authentication with an API key and secret at ssapi.shipstation.com, allows 40 requests a minute per key set, and is deprecated. V2 uses one key in an API-Key header at api.shipstation.com/v2, allows 200 requests a minute by default, and models shipments and labels rather than orders. Accounts can hold two V1 key sets but only one V2 key.

Can the ShipStation API find an order by customer email? No. V1's List orders filters by order number, customer name, dates, status, store and item keyword, and V2's List shipments filters by shipment number, ship-to name, sales order ID and dates. Match the customer's email in your store, such as Shopify, then look up ShipStation by order number, keeping only the exact match because V1's order number filter is a starts-with search.

Can an AI agent void a ShipStation label? The API allows it: V1 voids by shipmentId with POST /shipments/voidlabel, and V2 voids by label_id with PUT /v2/labels/{label_id}/void. ShipStation warns that voided labels can't be un-voided, the carrier's void window applies (28 days for USPS and 30 for UPS on ShipStation carriers), and manual USPS voids lose Refund Assist, so we'd leave voids to a person.

Does Gorgias AI Agent work with ShipStation? Yes. Gorgias documents three AI Agent actions for ShipStation: Get order info, Update shipping address and Cancel order, the last two only when the ShipStation orderStatus isn't shipped or canceled. Setup uses a ShipStation V1 API key and secret generated by a ShipStation admin, and a refund on a canceled order also needs Gorgias's Cancel Shopify order action.

Is there a ShipStation app for Zendesk? Yes. ShipStation publishes a free Zendesk app that lets agents pull, search and view recent order data in the ticket sidebar using a ShipStation API key and secret. It displays data for a person and takes no actions. On 28 September 2026 the marketplace showed 7 ratings averaging 2 out of 5.

How we researched this

• ShipStation documentation, read 28 September 2026: Security & Authentication, Usage & Rate Limits, Products and Plans, V2 Getting Started, Void Labels; V2 reference: List shipments, Update a shipment, Cancel a shipment, Void a label, List labels, Get label tracking; V1 reference: Requirements, List orders, List shipments, Create or update order, Hold order until, Restore from hold, Void label and Delete order.
• Pricing and popularity, read 28 September 2026: ShipStation's pricing page at the 50-shipment tier on monthly billing, including the "API access" row in its plan comparison; the Shopify App Store listing (4.2 from 707 reviews; "Shipping API" on Standard at $29.99).
• Integrations, read 28 September 2026: Gorgias's AI Agent Actions: Connect AI Agent to ShipStation; ShipStation's app on the Zendesk Marketplace. The 335 installs, 7 ratings averaging 2 and July 2018 last version come from Zendesk's public marketplace app feed (app 161092); the listing page itself rounds installs to "200+".
• Arithmetic: $29.99 − $14.99 = $15.00 a month. V1: 40 requests a minute ÷ 2 calls per ticket = 20 tickets a minute. V2: 200 ÷ 2 = 100 tickets a minute.
• What we ran live, and what we didn't: on 28 September 2026 we built three ShipStation custom tools on our Macha Demo test org with placeholder credentials and pressed Run Test on each; all three got HTTP 401. We ran two agents through Macha's Test feature, creating tickets #1124 and #1151 in our d3v-macha Zendesk sandbox; the model was GPT-5.4, Macha's current default. We have no ShipStation account with API access, so we never saw a successful response, a hold or a void, and everything past the 401 is built from ShipStation's documentation. Gorgias AI Agent's ShipStation actions and ShipStation's Zendesk app are described from their documentation; we didn't run them. The instruction shown is the one we ran, except that "cancelled" in its own wording was changed to "canceled" afterward. Every customer, email, address and ticket here is synthetic.

ShipStation merchants can start a trial with $50 of free usage (about 125 tickets), no credit card, no time limit, and Macha's team will set up the ShipStation tools during onboarding. Tiers are on the pricing page.