Getting Started


In order to make requests, you will first need to get a token that validates your identity. You get a token by authenticating with your user credentials. Once you have it, every request made to the API has to include it as part of the Authentication header.

Note: API keys are no longer needed for the new API, just using your credentials to get the token is enough to start making requests. If you would like to have a special or unique user for the public API, you can always create one and use it to get the tokens and make requests.

ShipHero's public API lives in https://public-api.shiphero.com, and there are two main endpoints:

1
https://public-api.shiphero.com/auth (used for getting tokens) 
2
https://public-api.shiphero.com/graphql (used for fetching and modifying your data)

The new API offers the same data as the old one plus a lot more new features. You can for example:

  • Browse inventory changes 
  • Browse order history 
  • Browse returns history 
  • Browse line item picks 
  • Search for returns and orders with better filters 
  • Granular operations for purchase orders 
  • and many more...

Identifiers

The resources exposed through the API have new identifiers. These ones are like uuids, which makes them opaque and lot different than the ones you are used to getting from previous versions. In order to maintain backward compatibility and make the transition easier, you can always request to include the legacy id, you just have to add the field legacy_id in the requested fields of your queries.

If you have an existing legacy id and want to obtain the corresponding uuid, you can also do that, by calling the query uuid and passing the legacy id along with the name of the entity (more on this later)

User quotas

In order to prevent abuse or misuse, there's a throttling strategy in place that's based on user quotas. This basically means that each user will have a number of credits to be used in a period of time, once this credit is consumed you won't be able to make further requests until the quota is refreshed (once the period expires and resets, usually an hour). Every operation made in the public API is measured in credits, and the cost of it depends on the complexity of the operation. 

When making queries the cost will vary depending on how many resources you fetch, how many relationships you navigate and a pre-defined complexity for each query. Learn more about user quotas here

Next steps