API INTEGRATION
POSTING ORDERS
The primary function of our API is to allow the posting of orders directly to our order management system. You can send us orders the moment they are placed. When you send us an order, we aim to provide you with all the necessary information, both in cases where the order was successfully received and those cases where it was not.
REQUEST/RESPONSE FORMATS
Both JSON and XML are supported. JSON is the default format for both requests and responses. A request must include a Content-Type header with a value of either application/json or application/xml. Any value other than these two results in a HTTP status code of 500, Internal Server Error. A request without a Content-Type header will result in a HTTP status code 400, Bad Request.
If the request does not include an Accept header, the response will be the default format, JSON.
A successful response will return a HTTP status code of either “201, Created” or “202, Accepted”. A 201 indicates that the order has been received by our order management database, while a 202 indicates that the order has been accepted, but a possible issue put the order in a pending status and is not yet in our order management database. 202 does mean we have the order and will contact you if there is anything else needed to get the order or future orders like it, into our database.
A Created response (201) will return a modified JSON request string. The following are noteworthy modifications:
| orderId | ShipRight specific id associated with the order. Used in an order status GET. |
| invoiceNumber | ShipRight specific invoice id. |
| standardized | The order API attempts to standardize addresses, and if successful sets this field = true. If the address has already been standardized prior to calling the API, set this field = true and the API will not attempt to standardize it. As of this writing, only US domestic addresses are standardized. |
| customerId | ShipRight specific id associated with the person placing the order. May be included for subsequent requests by the same person. |
Go here for an example JSON Response, with these additional modifications.
An Accepted response (202) will also return a modified JSON request string with orderId, invoiceNumber and customerId set to 0. This is because the order has not yet been processed by ShipRight’s order management system.
Included in a successful response is a HTTP ‘Link’ header with a URI to order status. A Created (201) response will look like this:
Link: https://api.shiprightsolutions.com/v1/order/4131299, where 4131299 is the order id.
An Accepted (202) response will look like this:
Link: https://api.shiprightsolutions.com/v1/order/-12345, where -12345 is a place holder for the order id. Note that this is a negative number.
See here for details.
STANDARD SHIPVIA CODES
You will need to send us a ShipVia Code, to determine what carrier and service will be used to ship the order. For details on where these codes are used, go to the Order Request Fields page.
The most common codes are:
| Code | Method Type | Description |
| RG1 | Standard | Ships UPS Mail Innovations, depending on weight, with final delivery made by the US Postal Service. |
| FC | Rush | Ships via the US Postal Service, either First Class or Priority Mail, depending on the weight of the package. |
| INT | International | Ships APC Postal Logistics, depending on weight. |
If you require additional codes for specific services, reach out to your ShipRight contact to request those codes.