Getting Started

The ShipSage let you build apps and other integrations using RESTful APIs. With the APIs, you can create apps that offer functionality at every stage of a warehouse's operation, including Account, Warehouse, Product, Inventory, Order, Shipping, ASN, Transfer, VAS (Value-Added Service), Return, and File Upload management.

Sandbox & Production

BASE URL

Name	URL
`Sandbox`	`https://app-sandbox.shipsage.com`
`Production`	`https://api.shipsage.com`

Please note that all data in the production environment is real data. If you need to test in the production environment, please contact ShipSage IT and ensure that all test data is cleaned up after testing.

Obtain access token method :

Method 1. Integration the marketplace platform like: Amazon, Shopify, Wayfair,Walmart…etc.;

Method 2. Integration the third party like ERP.

Method 1:

Step1: Contact our customer service to get auth information

Example

Name	Value
`client_id`	`1780`
`client_secret`	`SyGIQzIvXYiLAL0HGeq49vJF5babOqPiQZLWxvxt`
`username`	`demo4173.vip`
`password`	`demo4173.vip`

Step2: Use auth information to request an access token

Endpoints `POST /oauth/token`

Request

Name	Value
`grant_type`	`password`
`client_id`	`1780`
`client_secret`	`SyGIQzIvXYiLAL0HGeq49vJF5babOqPiQZLWxvxt`
`username`	`demo4173.vip`
`password`	`demo4173.vip`

Response

Name	Value
`token_type`	`Bearer`
`expires_in`	`31536000`
`access_token`	`eyJ0eXAiOiJKV1QiLCJhbGciOi ...`
`refresh_token`	`def5020081e6cf553ed6d0596 ...`

Demo

Method 2:

Step1: Contact our customer service to get auth information

You should provide some information to our customer service

redirect_uri: after the auth successfully, auto jump to this uri,by this, you can obtain the code which is required for obtain the access token

Our customer service will give you required information to start the authorize flow.

client_id: Integer Type. such as 100

client_secret: String type. such as 'jLiOm1g4zm09R8jSsOIR5zjn2rHIAUU39USC1oBs'

Step2: Contact your customer to visit this url to give the authorization to you, after finish this step, you can access the code in the redirect uri, and you should store this code to obtain the access_token

Endpoints `BASE URL/developer/auth/authorize?client_id=client_id&scope=&state=`

Name	Value
`client_id`	`our customer service provided`
`scope`	`leave this field empty`
`state`	`this field is optional, which if input will remain in the redirect uri after the authorization.you can also leave this field empty`

Step3: Use auth information to request an access token

Endpoints `POST /oauth/token`

Request

Name	Value
`grant_type`	`authorization_code`
`client_id`	`1502`
`client_secret`	`jLiOm1g4zm09R8jSsOIR5zjn2rHIAUU39USC1oBs`
`code`
`redirect_uri`

Response

Name	Value
`token_type`	`Bearer`
`expires_in`	`31536000`
`access_token`	`eyJ0eXAiOiJKV1QiLCJhbGciOi ...`
`refresh_token`	`def5020081e6cf553ed6d0596 ...`

Demo

Use refresh_token to request an access token

Endpoints `POST /oauth/token`

Request

Name	Value
`grant_type`	`refresh_token`
`client_id`	`1502`
`refresh_token`	`eyJ0eXAiOiJKV1QiLCJhbGciOi ...`
`client_secret`	`jLiOm1g4zm09R8jSsOIR5zjn2rHIAUU39USC1oBs`

Response

Name	Value
`token_type`	`Bearer`
`expires_in`	`31536000`
`access_token`	`eyJ0eXAiOiJKV1QiLCJhbGciOi ...`
`refresh_token`	`def5020081e6cf553ed6d0596 ...`

Demo

Set access token in header `Authorization: Bearer xxxx.access-token.xxxx` to request APIs

Endpoints `GET /api/developer/examples`

Header

Name	Value
`Authorization`	`Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi ...`

Response

Name	Value
`errcode`	`0`
`errmsg`	`ok`
`data`	`[...]`

Demo

Meaning of 'next_token'

'next_token' is an encrypted string used to get 50 pieces of data on the next page，ShipSage API returns a maximum of 50 pieces of data. If there are more than 50 pieces of data, there will be a 'next_token' after the last piece of data. Enter this 'next_token' into the request parameter and call this API again to return 50 pieces of data on the next page and the next the 'next_token' of the page, and so on.

Error Codes

All ShipSage API endpoints return a uniform JSON envelope. Use errcode as the sole indicator of success or failure — the HTTP status alone is not sufficient.

Response Envelope

Every response — success or failure — follows the same shape:

{
    "errcode": 0,
    "errmsg":  "ok",
    "data":    { ... }
}

Field	Type	Description
`errcode`	integer	`0` on success. Any non-zero value is an error.
`errmsg`	string	Human-readable message. For business errors (`99999`) this is safe to show the end user; for other codes it is a generic notice.
`data`	object / array / null	Response payload. Absent or empty on error.

Error Code Reference

errcode	HTTP	Category	Meaning
0	200	Success	Request processed successfully.
99999	200	Business Validation	Expected business rule violation — missing field, invalid state, resource not found, etc. The `errmsg` describes the exact reason and is safe to display to the end user.
50000	200	Internal Error	Unexpected server-side exception. The `errmsg` is a generic notice; a request trace id is prefixed in square brackets.
40000	200	Access Denied	Authenticated, but the token has no access to the target company / resource (e.g. `No Company Access`, `No Access`).
401	401	Unauthenticated	Access token is missing, invalid, or expired. Response uses the field `message` instead of `errmsg`.
429	429	Rate Limited	Too many requests. The `errmsg` includes the request path that was throttled.

Example Responses

Success

{
    "errcode": 0,
    "errmsg":  "ok",
    "data": {
        "transfer_id": 108220,
        "status":      "OPEN"
    }
}

99999 — Business Validation Error

Returned when the request fails a business rule. The message is deterministic and safe to show the user.

{
    "errcode": 99999,
    "errmsg":  "shipments is required when is_dc_packing_list is 0",
    "data":    null
}

{
    "errcode": 99999,
    "errmsg":  "Transfer 108220 not found",
    "data":    null
}

{
    "errcode": 99999,
    "errmsg":  "VAS 55123 is already cancelled",
    "data":    null
}

50000 — Internal Server Error

The exact exception is logged on our side. The errmsg is a generic notice prefixed with a trace id — share this trace id with ShipSage support to look up the full stack.

{
    "errcode": 50000,
    "errmsg":  "[abc123def456][2026-10-16T10:12:34+00:00] Sorry, the operation failed, please contact the administrator.",
    "data":    null
}

40000 — Access Denied

{
    "errcode": 40000,
    "errmsg":  "No Company Access",
    "data":    []
}

401 — Unauthenticated

Note: this response uses the field message instead of errmsg.

{
    "message": "Unauthenticated."
}

429 — Rate Limited

{
    "errcode": 429,
    "errmsg":  "Too Many Requests api/v202608/transfers"
}

Integration Guidance

Handle responses with just two rules:

errcode == 0 — success. Read data.

errcode != 0 — error. Branch on the code:

Code	How to handle
`99999`	A deterministic business error. Show `errmsg` to the end user, or map it to your own UI. Do not retry — the same input will fail again.
`50000`	A server-side exception. Capture the leading `[trace_id]` from `errmsg` and send it to ShipSage support. Safe to retry after a short back-off, but repeated failures should be reported.
`40000`	The access token does not have the required permission or company scope. Verify your credentials and the company context of the request.
`401`	Re-authenticate and retry with a fresh access token.
`429`	Back off and retry. Respect the `Retry-After` header if present.

Reporting an issue

When contacting ShipSage support about an error, please include:

The full response body (so we have errcode, errmsg, and the trace id).

The request method, URL, and the exact payload you sent.

The approximate timestamp (UTC) of the request.

With the trace id we can retrieve the full server-side log and reach a resolution faster.

Sandbox & Production#

BASE URL#

Obtain access token method :#

Method 1:#

Step1: Contact our customer service to get auth information#

Example#

Step2: Use auth information to request an access token#

Endpoints POST /oauth/token#

Request#

Response#

Demo#

Method 2:#

Step1: Contact our customer service to get auth information#

Step2: Contact your customer to visit this url to give the authorization to you, after finish this step, you can access the code in the redirect uri, and you should store this code to obtain the access_token#

Endpoints BASE URL/developer/auth/authorize?client_id=client_id&scope=&state=#

Step3: Use auth information to request an access token#

Endpoints POST /oauth/token#

Request#

Response#

Demo#

Use refresh_token to request an access token#

Endpoints POST /oauth/token#

Request#

Response#

Demo#

Set access token in header Authorization: Bearer xxxx.access-token.xxxx to request APIs#

Endpoints GET /api/developer/examples#

Header#

Response#

Demo#

Meaning of 'next_token'#

Error Codes#

Response Envelope#

Error Code Reference#

Example Responses#

Success#

99999 — Business Validation Error#

50000 — Internal Server Error#

40000 — Access Denied#

401 — Unauthenticated#

429 — Rate Limited#

Integration Guidance#

Reporting an issue#

Sandbox & Production

BASE URL

Obtain access token method :

Method 1:

Step1: Contact our customer service to get auth information

Example

Step2: Use auth information to request an access token

Endpoints `POST /oauth/token`

Request

Response

Demo

Method 2:

Step1: Contact our customer service to get auth information

Step2: Contact your customer to visit this url to give the authorization to you, after finish this step, you can access the code in the redirect uri, and you should store this code to obtain the access_token

Endpoints `BASE URL/developer/auth/authorize?client_id=client_id&scope=&state=`

Step3: Use auth information to request an access token

Endpoints `POST /oauth/token`

Request

Response

Demo

Use refresh_token to request an access token

Endpoints `POST /oauth/token`

Request

Response

Demo

Set access token in header `Authorization: Bearer xxxx.access-token.xxxx` to request APIs

Endpoints `GET /api/developer/examples`

Header

Response

Demo

Meaning of 'next_token'

Error Codes

Response Envelope

Error Code Reference

Example Responses

Success

99999 — Business Validation Error

50000 — Internal Server Error

40000 — Access Denied

401 — Unauthenticated

429 — Rate Limited

Integration Guidance

Reporting an issue