A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The ShipStation API is how an app or AI agent works with a fulfillment account: importing an order, comparing carrier rates, buying and printing a shipping label, marking an order as shipped, and managing warehouses, products, and connected stores. Access is granted through a single API key and secret pair that authenticates every call, and that credential carries full account access rather than per-area permissions. ShipStation can also push a notification to a registered address when an order arrives or a label is created.
How an app or AI agent connects to ShipStation determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the API credential behind it. ShipStation also publishes a documentation server for AI agents that explains the API without making calls.
The V1 REST API takes JSON request bodies, returns JSON, and pages through lists with page and pageSize, at https://ssapi.shipstation.com. A call authenticates with an API key and secret combined into an HTTP Basic credential. The credential carries full account access, with no per-area scopes.
ShipStation POSTs a small JSON payload to a registered target URL when an event happens, like a new order or a new shipping label. The payload carries a resource_url that the receiver then calls with its own credential to fetch the affected records. Subscriptions are managed through the webhooks endpoints.
ShipStation hosts a first-party Model Context Protocol server at https://docs.shipstation.com/mcp that exposes its API documentation and reference material to AI agents and LLM clients, so an agent can explore endpoints, schemas, and examples. It is documentation only and does not make live API calls; calling the API still needs a real credential.
The V1 API authenticates with an API key and an API secret, combined as key:secret, Base64-encoded, and sent in the Authorization header as an HTTP Basic credential on every request. Only the account owner can generate the pair, after verifying their email. The credential has full account access and carries no scopes, so it can read and write every area.
The ShipStation API is split into areas an agent can act on, like orders, shipments, carriers, warehouses, products, and stores. Each area has its own methods, and writes in some areas buy postage, create labels, or change order data.
Methods for importing, reading, updating, and fulfilling orders.
Methods for rating, buying, and voiding shipping labels.
Methods for reading carrier accounts, services, and packages, and adding postage funds.
Methods for managing ship-from and return locations.
Methods for reading and updating the product catalog.
Methods for reading and refreshing connected sales channels.
Methods for subscribing to and removing event notifications.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
OrdersMethods for importing, reading, updating, and fulfilling orders.7 | ||||||
| GET | /orders | List orders, filtered by status, store, customer, dates, and other criteria. | read | — | Current | |
Read-only. V1 has no scopes; any valid key can call this. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /orders/{orderId} | Retrieve a single order by its ShipStation order ID. | read | — | Current | |
Read-only. V1 has no scopes; any valid key can call this. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /orders/createorder | Create a new order or update an existing one by matching order number and store. | write | — | Current | |
Upsert: creates a new order or overwrites a matching one. V1 has no scopes. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook event ORDER_NOTIFYRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /orders/markasshipped | Mark an order as shipped without buying a label in ShipStation, optionally with tracking. | write | — | Current | |
Can notify the customer and the sales channel. V1 has no scopes. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /orders/{orderId}/createLabel | Buy and create a shipping label for an existing order. | write | — | Current | |
Buys postage against the order's carrier account. V1 has no scopes. Acts onlabel Permission (capability)None required VersionAvailable since the API’s base version Webhook event SHIP_NOTIFYRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /orders/{orderId}/hold | Place an order on hold until a given date so it is not processed. | write | — | Current | |
Changes order status to on-hold. V1 has no scopes. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /orders/{orderId} | Delete an order, moving it to the deleted-orders state. | write | — | Current | |
Soft-deletes the order. V1 has no scopes. Acts onorder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Shipments & labelsMethods for rating, buying, and voiding shipping labels.4 | ||||||
| GET | /shipments | List shipments that have labels generated in ShipStation, with filters and date ranges. | read | — | Current | |
Read-only. Only shipments with generated labels are returned. V1 has no scopes. Acts onshipment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /shipments/getrates | Get a list of available shipping rates for a shipment across a carrier's services. | read | — | Current | |
A POST that reads rates and creates nothing. V1 has no scopes. Acts onrate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /shipments/createlabel | Buy and create a shipping label for a shipment without referencing an order. | write | — | Current | |
Buys postage. Set testLabel to avoid a real purchase. V1 has no scopes. Acts onlabel Permission (capability)None required VersionAvailable since the API’s base version Webhook event SHIP_NOTIFYRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /shipments/voidlabel | Void a label that was created in ShipStation, requesting a refund where the carrier allows it. | write | — | Current | |
Voids a real label and may trigger a postage refund. V1 has no scopes. Acts onlabel Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CarriersMethods for reading carrier accounts, services, and packages, and adding postage funds.5 | ||||||
| GET | /carriers | List the carrier accounts connected to the ShipStation account. | read | — | Current | |
Read-only; the response includes each carrier's balance. V1 has no scopes. Acts oncarrier Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /carriers/getcarrier?carrierCode={carrierCode} | Retrieve a single carrier account, including its postage balance. | read | — | Current | |
Read-only. V1 has no scopes. Acts oncarrier Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /carriers/listservices?carrierCode={carrierCode} | List the shipping services available for a given carrier. | read | — | Current | |
Read-only. V1 has no scopes. Acts onservice Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /carriers/listpackages?carrierCode={carrierCode} | List the package types available for a given carrier. | read | — | Current | |
Read-only. V1 has no scopes. Acts onpackage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /carriers/addfunds | Add postage funds to a carrier account that ShipStation manages, such as Stamps.com. | write | — | Current | |
Moves real money into the carrier's postage balance. V1 has no scopes. Acts oncarrier Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WarehousesMethods for managing ship-from and return locations.4 | ||||||
| GET | /warehouses | List the warehouses (ship-from and return locations) on the account. | read | — | Current | |
Read-only. V1 has no scopes. Acts onwarehouse Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /warehouses | Create a new warehouse with a ship-from and an optional return address. | write | — | Current | |
Adds a new ship-from location. V1 has no scopes. Acts onwarehouse Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /warehouses/{id} | Update an existing warehouse's addresses and settings. | write | — | Current | |
Overwrites the warehouse record. V1 has no scopes. Acts onwarehouse Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /warehouses/{id} | Delete a warehouse from the account. | write | — | Current | |
Removes a ship-from location. V1 has no scopes. Acts onwarehouse Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProductsMethods for reading and updating the product catalog.3 | ||||||
| GET | /products | List products in the ShipStation catalog, with filters and pagination. | read | — | Current | |
Read-only. V1 has no scopes. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /products/{productId} | Retrieve a single product by its ID. | read | — | Current | |
Read-only. V1 has no scopes. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /products/{productId} | Update a product. The full product object must be sent; partial updates are not supported. | write | — | Current | |
Overwrites the whole product record. V1 has no scopes. Acts onproduct Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
StoresMethods for reading and refreshing connected sales channels.4 | ||||||
| GET | /stores | List the sales channels (stores) connected to the account. | read | — | Current | |
Read-only. V1 has no scopes. Acts onstore Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /stores/{storeId} | Retrieve a single store's details and settings. | read | — | Current | |
Read-only. V1 has no scopes. Acts onstore Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /stores/refreshstore | Trigger a sync that pulls new orders from a connected store into ShipStation. | write | — | Current | |
Starts a store sync that imports orders. V1 has no scopes. Acts onstore Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /stores/marketplaces | List the marketplaces and sales channels ShipStation can connect to. | read | — | Current | |
Read-only. V1 has no scopes. Acts onmarketplace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksMethods for subscribing to and removing event notifications.3 | ||||||
| GET | /webhooks | List the webhook subscriptions registered on the account. | read | — | Current | |
Read-only. V1 has no scopes. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /webhooks/subscribe | Subscribe to an event by registering a target URL and an event type. | write | — | Current | |
Sets where ShipStation POSTs event notifications. V1 has no scopes. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /webhooks/{webhookId} | Remove a webhook subscription so notifications stop. | write | — | Current | |
Stops event notifications to that endpoint. V1 has no scopes. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ShipStation can notify an app when something happens in an account, like a new order arriving or a label being created. It POSTs a small payload with a link to fetch the affected records, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
ORDER_NOTIFY | A new order was imported into ShipStation. The payload links to the matching orders so an integration can fetch them. | /orders/createorder |
ITEM_ORDER_NOTIFY | A new order arrived, delivered with item-level detail so an integration can read the line items, not just the order. | /orders/createorder |
SHIP_NOTIFY | A new outbound shipping label was created for an order. The payload links to the resulting shipment records. | /shipments/createlabel/orders/{orderId}/createLabel |
ITEM_SHIP_NOTIFY | A new shipping label was created, delivered with item-level shipment detail so an integration can read what shipped. | /shipments/createlabel/orders/{orderId}/createLabel |
ShipStation limits how fast an app can call, by a fixed number of requests per minute per API credential, and reports the remaining allowance on every response.
ShipStation V1 meters by a fixed request rate, not by a per-method cost or point weighting. Each API key and secret pair is allowed 40 requests per minute. Every response reports the current state in three headers: X-Rate-Limit-Limit is the ceiling, X-Rate-Limit-Remaining is how many requests are left in the window, and X-Rate-Limit-Reset is the seconds until the window resets. Exceeding the limit returns HTTP 429 with a body of {"message": "Too Many Requests"}, so a client should watch the remaining header and slow down before it is exhausted.
List endpoints page through results with page and pageSize query parameters. The response reports total, page, and pages so a caller knows how many records and pages exist. Sort order is controlled with sortBy and sortDir on the endpoints that support it.
A list page can request up to 500 records with pageSize, which is the maximum the V1 API accepts. Larger result sets are read by walking the page numbers up to the reported page count.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a parameter was invalid, for example a missing required field on a create call. | Read the message in the response, fix the request body or parameters, and resend. The request is not retryable as-is. |
| 401 | Unauthorized | No valid credential was provided, or the API key and secret were wrong or wrongly encoded. | Confirm the key and secret are correct, combined as key:secret, and Base64-encoded into the Authorization header. |
| 403 | Forbidden | The credential is valid but the account is not permitted to perform the request, for example a plan that does not include V1 API access. | Check the account's plan tier and entitlements; V1 access requires a Standard or Accelerate plan or higher. |
| 404 | Not Found | The requested record does not exist, or the path was wrong, for example an order ID that is not in the account. | Verify the resource ID and the request path, and confirm the record belongs to this account. |
| 405 | Method Not Allowed | The HTTP method is not supported on that path, for example a GET on a create-only endpoint. | Use the method the endpoint documents for that operation. |
| 429 | Too Many Requests | The 40-requests-per-minute limit for the API key and secret was exceeded. The body reads {"message": "Too Many Requests"}. | Back off and retry after the window resets, watching X-Rate-Limit-Remaining and X-Rate-Limit-Reset to pace calls. |
| 500 | Internal Server Error | An error on ShipStation's side, which is rare. | Retry after a short delay with backoff, and contact ShipStation support if it persists. |
ShipStation runs two separate APIs side by side. The original API documented here is unversioned and known as V1, while a newer V2 API, rebranded from ShipEngine in early 2025, runs alongside it.
The original ShipStation API, active for over a decade at ssapi.shipstation.com. It is unversioned, with no dated release string, and covers orders, shipments, carriers, warehouses, products, stores, customers, fulfillments, and webhooks. It authenticates with an API key and secret over HTTP Basic auth and meters at 40 requests per minute.
On 28 February 2025, the API formerly known as ShipEngine was rebranded as the ShipStation API, now called V2. It runs alongside V1 as a separate, shipping-focused API for labels, rates, carriers, warehouses, batches, and manifests, with a different host, an API-Key header credential, and its own release notes. New integrations are steered toward V2.
V1 is stable and unversioned; plan a future move to V2, which ShipStation is steering new integrations toward.
ShipStation API release notes ↗Bollard AI sits between a team's AI agents and ShipStation. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.