Partner API

The Partner API is not open to the general public. If you are interested in a ShippingEasy Partner API account, please contact support@shippingeasy.com.

Making requests via curl

First you will need to create an API signature. Concatenate these into a plaintext string using the following order:

1. Capitilized method of the request. E.g. "POST"
2. The URI path
3. The query parameters sorted alphabetically and concatenated together into a URL friendly format: param1=ABC&param2=XYZ
4. The request body as a string if one exists

All parts are then concatenated together with an ampersand. The result resembles something like this:

"POST&/partners/api/accounts&api_key=f9a7c8ebdfd34beaf260d9b0296c7059&api_timestamp=1401803554&{"{\"account\":{\"first_name\":\"Coralie\",\"last_name\":\"Waelchi\",\"company_name\":\"Hegmann, Cremin and Bradtke\",\"email\":\"se_greg_6d477b1e59e8ff24abadfb59d3a2de3e@shippingeasy.com\",\"phone_number\":\"1-381-014-3358\",\"address\":\"2476 Flo Inlet\",\"address2\":\"\",\"state\":\"SC\",\"city\":\"North Dennis\",\"postal_code\":\"29805\",\"country\":\"USA\",\"password\":\"abc123\",\"subscription_plan_code\":\"starter\"}}"

Finally, using your Partner API secret encrypt the string using HMAC sha256. In ruby, it looks like this:

OpenSSL::HMAC::hexdigest("sha256", api_secret, "POST&/partners/api/accounts&api_key=f9a7c8ebdfd34beaf260d9b0296c7059&api_timestamp=1401803554&{"{\"account\":{\"first_name\":\"Coralie\",\"last_name\":\"Waelchi\",\"company_name\":\"Hegmann, Cremin and Bradtke\",\"email\":\"se_greg_6d477b1e59e8ff24abadfb59d3a2de3e@shippingeasy.com\",\"phone_number\":\"1-381-014-3358\",\"address\":\"2476 Flo Inlet\",\"address2\":\"\",\"state\":\"SC\",\"city\":\"North Dennis\",\"postal_code\":\"29805\",\"country\":\"USA\",\"password\":\"abc123\",\"subscription_plan_code\":\"starter\"}}")

API timestamp

You must include an API timestamp in your requests. The timestamp should be an integer representation of the current time (also known as Unix epoch time).

Account Creation

A partner may create ShippingEasy accounts on behalf of their customers. The first time a customer logs into an account created via the partner API they will be prompted to provide billing information. Their subscription plan will be preset to whatever plan was sent in the account creation payload.

curl -H "Content-Type: application/json" --data @body.json "https://app.shippingeasy.com/partners/api/accounts?api_key=f9a7c8ebdfd34beaf260d9b0296c7059&api_timestamp=1401803554&api_signature=c65f43beed46e581939898a78acd10064cfa146845e97885ec02124d7ad648e4"

Note: For this example to work you must sign the request using your own API key and secret with a recent timestamp

An example body.json can be found here:

https://gist.github.com/twmills/94433a409df0ac5960c4

Example Response

{"account":{"id":3,"company_name":"Hegmann, Cremin and Bradtke","email":"se_greg_4a5cc5c42304d07e5af66a382948f56a@shippingeasy.com","phone_number":"1-381-014-3358","first_name":"Coralie","last_name":"Waelchi"}}

Validation Errors

Our API returns a 400 status code along with a JSON payload when validation errors occur. Here’s an example payload where every validation error is triggered, except for the unique constraint on email address:

{"errors":"{\"email\":[\"is not valid\",\"can't be blank\"],\"company_name\":[\"can't be blank\"],\"phone_number\":[\"can't be blank\"],\"first_name\":[\"can't be blank\"],\"last_name\":[\"can't be blank\"],\"address\":[\"can't be blank\"],\"city\":[\"can't be blank\"],\"state\":[\"can't be blank\"],\"postal_code\":[\"can't be blank\"],\"country\":[\"can't be blank\"],\"password\":[\"can't be blank\"],\"subscription_plan_code\":[\"can't be blank\",\"is not included in the list\"]}”}

And here’s the error returned when an email address already has an account in our system:

{"errors":"{\"email\":[\"already has an account associated with it\"]}"}

List of subscription plans

In order to create an account you will need to pass the subscription plan code in the account creation payload. The following example call can be made to return a list of available plan codes:

curl "https://app.shippingeasy.com/partners/api/subscription_plans?api_key=4c6c81c1b43b4e4830001f5db196c4b6&api_signature=cfa1b055c5d617df1c6f7ddcce7e3f54aced1ff4ed59cf4f9a0295f472042b04&api_timestamp=1404923397"

Note: For this example to work you must sign the request using your own API key and secret with a recent timestamp

Response

{"subscription_plans":[{"code":"starter_blackjack","name":"Starter","cost":"0.00","number_of_shipments":50},{"code":"basic","name":"Basic","cost":"29.00","number_of_shipments":500},{"code":"plus","name":"Plus","cost":"49.00","number_of_shipments":1500},{"code":"select_69","name":"Select","cost":"69.00","number_of_shipments":3000},{"code":"premium_99","name":"Premium","cost":"99.00","number_of_shipments":6000},{"code":"enterprise","name":"Enterprise","cost":"149.00","number_of_shipments":12500}]}