ShipStation User Management API Guide

Auth method: HTTP Basic Auth (API Key as username, API Secret as password, Base64-encoded)

Setup steps

1. Log in to ShipStation and navigate to Account Settings > API Settings.
2. Generate an API Key and API Secret.
3. Base64-encode the string 'API_KEY:API_SECRET'.
4. Pass the encoded value in the Authorization header as: 'Authorization: Basic '.

User object field mapping is not yet verified for this app.

List Orders

• Method: GET
• URL: https://ssapi.shipstation.com/orders
• Watch out for: No user-management endpoint exists; this is the primary resource endpoint for reference.

Request example

GET /orders?orderStatus=awaiting_shipment&pageSize=25&page=1
Authorization: Basic <encoded>

Response example

{
  "orders": [...],
  "total": 150,
  "page": 1,
  "pages": 6
}

Get Order

• Method: GET
• URL: https://ssapi.shipstation.com/orders/{orderId}
• Watch out for: orderId is ShipStation's internal integer ID, not the store's order number.

Request example

GET /orders/123456789
Authorization: Basic <encoded>

Response example

{
  "orderId": 123456789,
  "orderNumber": "TEST-001",
  "orderStatus": "awaiting_shipment"
}

List Shipments

• Method: GET
• URL: https://ssapi.shipstation.com/shipments
• Watch out for: Voided shipments are included unless filtered with includeShipmentItems parameter.

Request example

GET /shipments?pageSize=100&page=1
Authorization: Basic <encoded>

Response example

{
  "shipments": [...],
  "total": 200,
  "page": 1,
  "pages": 2
}

List Stores

• Method: GET
• URL: https://ssapi.shipstation.com/stores
• Watch out for: Returns stores associated with the authenticated account only; no cross-account access.

Request example

GET /stores?showInactive=false
Authorization: Basic <encoded>

Response example

[
  {
    "storeId": 12345,
    "storeName": "My Store",
    "marketplaceId": 36
  }
]

List Warehouses

• Method: GET
• URL: https://ssapi.shipstation.com/warehouses
• Watch out for: Warehouse management is account-scoped; no user-level warehouse assignment via API.

Request example

GET /warehouses
Authorization: Basic <encoded>

Response example

[
  {
    "warehouseId": 9876,
    "warehouseName": "Main Warehouse",
    "isDefault": true
  }
]

• Rate limits: Rate limits are enforced per API key and vary by ShipStation plan. The API returns an X-Rate-Limit-Limit header (requests allowed per window), X-Rate-Limit-Remaining header (requests remaining), and X-Rate-Limit-Reset header (seconds until window resets).
• Rate-limit headers: Yes
• Retry-After header: No
• Rate-limit notes: When the rate limit is exceeded, the API returns HTTP 429. The X-Rate-Limit-Reset header indicates seconds until the window resets. Retry-After header is not documented as returned.
• Pagination method: offset
• Default page size: 100
• Max page size: 500
• Pagination pointer: page and pageSize

• Webhooks available: Yes
• Webhook notes: ShipStation supports webhooks that fire on specific shipping events. Webhooks are configured in the ShipStation UI (Account Settings > Webhooks) or via the API POST /webhooks/subscribe endpoint.
• Alternative event strategy: Polling the /orders or /shipments endpoints with a modifyDateStart filter can substitute for webhook delivery if webhook receipt is unreliable.
• Webhook events: ORDER_NOTIFY, ITEM_ORDER_NOTIFY, SHIP_NOTIFY, ITEM_SHIP_NOTIFY

• SCIM available: No
• SCIM version: Not documented
• Plan required: Not documented
• Endpoint: Not documented

Limitations:

• ShipStation does not offer a SCIM 2.0 API for user provisioning or deprovisioning.
• User and sub-user management is only available through the ShipStation web UI.
• Okta integration exists but is limited to SSO (SAML); automated provisioning via SCIM is not supported.

Three integration patterns are well-supported by the current API surface.

For shipment tracking retrieval, paginate GET /shipments with shipDateStart and pageSize=500;

voided shipments are returned by default and must be filtered client-side using the voided boolean field.

For event-driven order processing, subscribe via POST /webhooks/subscribe with an ORDER_NOTIFY or SHIP_NOTIFY event - webhook payloads deliver only a resource_url, requiring a follow-up GET to retrieve the full object.

For multi-store data scoping, call GET /stores after UI-side store creation to retrieve storeId values, then use them as filter parameters on /orders and /shipments calls;

store creation itself cannot be performed via the API.

Automate shipment tracking retrieval

1. Authenticate using Base64-encoded API Key:API Secret in the Authorization header.
2. GET /shipments?shipDateStart=2024-01-01&pageSize=500&page=1 to retrieve shipments.
3. Iterate through pages using the 'pages' field in the response until all records are fetched.
4. Extract trackingNumber and carrierCode fields for downstream processing.

Watch out for: Voided shipments are returned by default; filter them out by checking the 'voided' boolean field on each shipment object.

Subscribe to order notifications via webhook

1. POST /webhooks/subscribe with body: {"target_url": "https://yourapp.com/hook", "event": "ORDER_NOTIFY", "store_id": null, "friendly_name": "Order Notifier"}
2. ShipStation will POST a JSON payload to target_url when new orders are detected.
3. Respond with HTTP 200 within the timeout window to acknowledge receipt.

Watch out for: ShipStation webhook payloads contain only a resource_url, not the full order object. A follow-up GET to that URL is required to retrieve order details.

Add a new store/channel to an existing account

1. Use the ShipStation web UI to connect a new marketplace or cart (API does not support store creation).
2. After creation, call GET /stores to retrieve the new storeId.
3. Use the storeId as a filter parameter in subsequent /orders or /shipments calls to scope data to that store.

Watch out for: Store creation and OAuth connections to marketplaces cannot be performed via the ShipStation API; they require UI interaction.

The core integration trap is assuming that API access implies any control over user identity or access state - it does not. ShipStation's API exposes shipping operations only; there is no endpoint to create, update, deactivate, or enumerate sub-users, making it impossible to wire ShipStation into an identity graph for joiner-mover-leaver automation.

Rate limits are enforced at 40 requests per minute on standard plans; HTTP 429 responses include an X-Rate-Limit-Reset header indicating seconds until window reset but no Retry-After header, so retry logic must be built against X-Rate-Limit-Reset explicitly. Pagination is 1-based offset with a maximum pageSize of 500;

the pages field in list responses is the reliable termination signal for full-dataset retrieval loops. The Apiary documentation may lag the live API - always cross-reference with the official help center for current endpoint behavior.