Tutorial

Stock, rates and orders

You can track your stock levels, get accurate shipping rates, and manage orders with the Shipwire API. Stock, rates and orders are RESTful resources and have their own API endpoints. Shipwire API represents stock, rate and order data as JSON objects. The following sections show examples of the main JSON blocks for each of these objects. For more information, view the full schema specifications for each resource’s data under API Resources.

A day in the life of a Shipwire application

The following sections describe common interactions between Shipwire services and a typical order-taking application. Our user – Audrey – is browsing through a mobile commerce application’s online catalog, looking to purchase some Jazz compilation CDs. As she navigates her app, we’ll detail the HTTP interaction with the Shipwire API.


Broadly speaking, our day goes as follows:

  1. The app checks stock availability of products and updates its catalog.
  2. Audrey browses the catalog and picks items to fill her shopping cart.
  3. When Audrey is ready, she proceeds to checkout, where she must select among different shipment rates and services.
  4. After Audrey confirms checkout, the app places a shipping order with Shipwire.
  5. Audrey realizes her order is one item short, so she modifies the original order and checks out again. The app updates the order with Shipwire.
  6. Once Shipwire ships Audrey’s packages, the app automatically sends Audrey a shipping confirmation email with her tracking number.

Let’s now peek under the hood.

Checking inventories

In advance, the app checks stock availability with Shipwire and updates its catalog. Then, the app shows Audrey which products are available in her area.


To check stock for an item, the app sends a GET request to the /stock resource in Shipwire API. The ?sku parameter in the URL selects which items to query.

GET /api/v3/stock?sku=Laura-s_Lament,TwinPianos HTTP/1.1
Host: api.beta.shipwire.com
Authorization: Basic TG9vayBhdCB0aGF0OyBEdWNrcy4uLm9uIGEgbGFrZSEK

 

In the response, Shipwire API returns a list of inventory manifests for each item. Each manifest specifies stock availability (good, pending, reserved, backordered, and so on) for each warehouse where the product exists.

{
"status": 200,
"message": "Successful",
"resourceLocation": null,
"resource": {
"offset": 0,
"total": 9,
"previous": null,
"next": null,
"items": [
{
"resourceLocation": null,
"resource": {
// Information about "Laura's Lament"
"productId": 1361533,
...
"sku": "Laura-s_Lament",
...
// Stock details
"warehouseId": 21,
...
"pending": 0,
"good": 74,
"reserved": 26,
"backordered": 0,
"shipping": 0,
"shipped": 0,
"creating": 0,
"consuming": 0,
"consumed": 0,
"created": 0,
"damaged": 0,
...
}
},
// Stock information for "Laura's Lament" in other warehouses
{
"resourceLocation": null,
"resource": {
"productId": 1361533,
...
"sku": "Laura-s_Lament",
...
"warehouseId": 37,
...
}
},
...
// Stock information for TwinPianos
{
"resourceLocation": null,
"resource": {
"productId": 1361533,
...
"sku": "TwinPianos",
...
"warehouseId": 21,
...
}
}
...
]
}
}


The above example is an excerpt from a /stock JSON document. Try out the Shipwire API and see a complete example in our  interactive console.


Using the /stock resource in Shipwire API, the app’s catalog shows Audrey which products are immediately available in her area. Audrey is happy to see she can get the products she needs, and starts filling her cart with items.

Creating shipment orders

With the /rate and /orders resources in the Shipwire API, shopping carts can set up and create shipping orders.


To set up an order, the app gets rates for different delivery services. Then, the app creates an order by specifying which products to ship, from which warehouse, to what customer address, and at which service level.


Currently, Shipwire supports the following service levels:


serviceLevelCode Type Description
GD Domestic: Ground Will include ground service levels. Will have variable service level commitments.
2D Domestic: 2 Day Will only include 2-Day time definite service levels options.
1D Domestic: 1 Day Will only include 1-day, overnight, service level options.
E-INTL International: Economy Will include the most cost-effective services available for international shipping. Can include services with little to no traceability, and that not insurable.
INTL International: Standard Will include the most cost-effective international services with some traceability. Will not usually have time-definite service commitments.
PL-INTL International: Plus Will include only traceable shipping methods, with time definite service levels.
PM-INTL International: Premium Will include only the fastest available shipping methods available.


When requesting a shipping rate, or creating an order, you can let Shipwire choose from the best available warehouse to handle the request. This choice will depend on several factors including your historical activity in the different warehouses, whether there is a domestic warehouse that can serve that order, and on a number of other shipping preferences for the account. Alternately, the Shipwire API allows you to force the warehouse selection by specifying a warehouse region as follows:

warehouseRegion Description
UK Requests the London warehouse
LAX Requests the Los Angeles warehouse
PHL Requests the Philadelphia warehouse
CHI Requests the Chicago warehouse
AUS Requests the Sydney warehouse
HKG Requests the Hong Kong warehouse
TOR Requests the Toronto warehouse
VAN Requests the Vancouver warehouse

Setting up orders

Audrey is now done filling her shopping cart and wants to check out. When she visits her cart checkout page, the app gives her real-time shipping rates for her to choose a delivery service.


To get shipping rates, the app sends a POST request to the /rate resource. The request specifies the items in Audrey’s cart, Audrey’s address, and some routing information.

POST /api/v3/rate HTTP/1.1
Host: api.beta.shipwire.com
Authorization: Basic TG9vayBhdCB0aGF0OyBEdWNrcy4uLm9uIGEgbGFrZSEK
Content-Type: application/json

{
"options": {
"currency": "USD",
"groupBy": "warehouse",
...
"warehouseArea": "US"
},
"order": {
"shipTo": {
"country": "US",
"address1": "6501 Railroad Avenue SE",
"address2": "Room 315",
"address3": "",
"city": "Snoqualmie",
"region": "WA",
"name": "Audrey Horne",
"isCommercial": 0,
"postalCode": "85283",
"isPoBox": 0
},
"items": [
{
"sku": "Laura-s_Lament",
"quantity": 1
},
{
"sku": "TwinPianos",
"quantity": 1
}
]
}
}


In the response, the Shipwire API returns best shipping rates based on our intelligent shipping optimization technology, along with package details and origin information. Also, the API returns expected shipment date and estimated delivery dates for each delivery option.

{
"status": 200,
"message": "Successful",
...
"resource": {
// Rates are grouped by warehouse location
"groupBy": "warehouse",
"rates": [
// Shipping from Los Angeles warehouse
{
"serviceOptions": [
// Ground delivery service rates
{
"serviceLevelCode": "GD",
"serviceLevelName": "Ground",
"shipments": [
// Shipment of product A
{
"warehouseName": "Los Angeles",
"carrier": {
"code": "USPS PM",
"name": "Ground",
"properties": [
"trackable"
]
},
"cost": {
"currency": "USD",
"type": "total",
"name": "Total",
"amount": 9.68,
"converted": false,
"originalCost": 9.68,
"originalCurrency": "USD"
},
...
"pieces": [
{
"length": { ... },
"width": { ... },
"height": { ... },
"weight": { ... },
...
"contents": [
{
"sku": "Laura-s_Lament",
"quantity": 1
}
]
}
],
"expectedShipDate": "2014-06-30T05:30:00-07:00",
"expectedDeliveryDateMin": "2014-07-02T05:30:00-07:00",
"expectedDeliveryDateMax": "2014-07-03T05:30:00-07:00"
},
// Shipment of product B
{ ... }
]
},
// Next day delivery service rates
{
"serviceLevelCode": "1D",
"serviceLevelName": "Next Day",
"shipments": [ ... ]
}
// Other delivery services
...
]
},
// Shipping from other locations
{ ... }
]
}
}


The above example is an excerpt from a /rates JSON document. Try out the Shipwire API and see a complete example in our interactive console.


From the information in the /rate response, the app can offer Audrey totals for each of the different service levels. The next step is to create a shipping order in Shipwire.

Creating orders

After reviewing shipping rates, Audrey selects overnight (1D) shipping for the items in her cart and confirms the purchase. Now the app creates the order in Shipwire to start the delivery service.


To create orders in Shipwire, the app sends POST requests to the /orders resource, specifying items to ship and shipping options.

POST /api/v3/orders HTTP/1.1
Host: api.beta.shipwire.com
Authorization: Basic TG9vayBhdCB0aGF0OyBEdWNrcy4uLm9uIGEgbGFrZSEK
Content-Type: application/json

{
"orderNo": "12345",
"externalId": "r44",
"processAfterDate": "2014-06-30T16:30:00-07:00",
"commerceName": "The Best Commerce",
"items": [
{
"sku": "Laura-s_Lament",
"quantity": 1,
},
{
"sku": "TwinPianos",
"quantity": 1,
}
],
"options": {
// The warehouse to ship from - 'null' means Shipwire should pick the optimal warehouse for me (default, recommended)
"warehouseId": null,
// Next Day shipping service
"serviceLevelCode": "1D",
...
},
"shipFrom": {"company": "We Sell'em Co."},
"shipTo": {
"email": "audrey.horne@greatnorthern.com",
"name": "Audrey Horne",
"address1": "6501 Railroad Avenue SE",
"address2": "Room 315",
"address3": "",
"city": "Snoqualmie",
"state": "WA",
"postalCode": "98065",
"country": "US",
"phone": "4258882556",
"isCommercial": 0,
"isPoBox": 0
},
// Message to include in packages
"packingList": {
"note": "This must be where pies go when they die. Enjoy!"
}
}


Note that if items are shipped from different warehouses and you have not chosen to split orders automatically, we recommend creating one order per warehouse. This avoids creating unnecessary holds.


In the response, the Shipwire API confirms the order has been created. It also returns important order information.

{
"status": 200,
"message": "Successful",
"resourceLocation": "https://api.beta.shipwire.com/api/v3/orders?offset=0&limit=2",
"resource": {
...
"items": [
{
"resourceLocation": "http://api.beta.shipwire.com/orders/12345",
"resource": {
// The ID to identify this order
"id": "12345",
...
// Order holds, item summary and tracking information
"holds": { ... },
"items": { ... },
"trackings": { ... },
"shipFrom": {
"resourceLocation": null,
"resource": {"company": "We Sell'em Co."}
},
// Audrey's address
"shipTo": { ... },
// Routing information
"routing": {
"resourceLocation": null,
"resource": {
"warehouseId": "11",
"warehouseExternalId": null,
"warehouseName": "LA",
"originLongitude": "34.0416",
"originLatitude": "-117.369",
"destinationLongitude": "-122.1738",
"destinationLatitude": "37.4337"
}
},
// Order events
"events": {
"resourceLocation": null,
"resource": {
"createdDate": "2014-06-10T13:48:44-07:00",
"pickedUpDate": null,
"submittedDate": null,
"processedDate": null,
"completedDate": null,
"expectedDate": "2014-06-12T00:00:00-07:00",
"deliveredDate": null,
"cancelledDate": null,
"returnedDate": null,
"lastManualUpdateDate": null
}
}
}
]
}
}


The previous example is an excerpt from an /orders JSON document. Try out the Shipwire API and see a complete example in our interactive console.


Now that the order has been created, everything is in Shipwire’s hands.

Updating orders

Oh, no! Audrey realizes her friend Dale’s birthday is coming soon. He would really enjoy a set of the Jazz collections she ordered. She should get a pair for him too. Luckily, with Shipwire, apps can update orders as long as they have not yet been processed. Audrey then navigates back to her shopping cart, and increases the number of items for each of her products. Then checks out once more.


To update Audrey’s order, the app sends the updated order payload in a PUT request to /orders/{id} resource. The {id} URL parameter identifies the order we are checking for status. In this case, we pass the ID for Audrey’s order.

PUT /api/v3/orders/12345 HTTP/1.1
Host: api.beta.shipwire.com
Authorization: Basic TG9vayBhdCB0aGF0OyBEdWNrcy4uLm9uIGEgbGFrZSEK
Content-Type: application/json

{
"items": [
{
// Adding Dale’s item
"sku": "Laura-s_Lament",
"quantity": 2,
},
{
// Adding Dale’s item
"sku": "Twin_Pianos",
"quantity": 2,
}
]
}

 

In the response, Shipwire API confirms the order has been updated.

{
"status": 200,
"message": "Successful",
"resourceLocation": "https://api.beta.shipwire.com/api/v3/orders?offset=0&limit=2",
"resource": {
...
"items": [
{
"resourceLocation": "http://api.beta.shipwire.com/orders/12345",
"resource": {
// The ID to identify this order
"id": "12345",
...
// More items here now!
"items": { ... },
...
}
}
]
}
}


The previous example is an excerpt from an /orders JSON document. Try out the Shipwire API and see a complete example in our interactive console.


Finally, Shipwire picks, packs, and hands off the order to the selected carrier.

Following orders and triggering workflows

The Shipwire API lets applications track order status. By polling order status, your app can automate your business flow according to different order events. Let’s see how the example app checks Audrey’s order status to automatically send her a shipping confirmation with a tracking number once her packages are shipped.


To track order status, the app polls the /orders/{id}/trackings resource with GET requests. The {id} URL parameter identifies the order we are checking for status. In this case, we pass the ID for Audrey’s order.

GET /api/v3/orders/12345/trackings HTTP/1.1
Host: api.beta.shipwire.com
Authorization: Basic TG9vayBhdCB0aGF0OyBEdWNrcy4uLm9uIGEgbGFrZSEK


By checking the summary field in the response, the app knows Shipwire shipped Audrey’s packages. A tracking number and the URL to the carrier’s tracking service webpage are returned in the tracking and URL fields.

{
"status": 200,
"message": "Successful",
"resourceLocation": "https://api.beta.shipwire.com/api/v3/orders/12345/trackings?offset=0&limit=20",
"resource": {
"offset": 0,
"total": 1,
"previous": null,
"next": null,
"items": [{
"resourceLocation": "http://api.beta.shipwire.com/api/v3/trackings/3",
"resource": {
"id": 3,
"orderId": 12345,
"orderExternalId": null,
"tracking": "70022286373",
"carrier": "FedEx",
"url": "https://ws.fedex.com/web-services/track?trackNumber=70022286373",
// Order has been shipped!
"summary": "2014-06-29, Status: Shipped, Location: US",
"summaryDate": "2014-06-29T08:57:04-08:00",
"trackedDate": "2014-06-29T08:57:04-08:00",
"deliveredDate": null
}
}]
}
}

 

Now the app knows to automatically send Audrey a shipping confirmation email with tracking numbers.


For visibility about an order’s current state, Shipwire supports the following events. All date/times are are in ISO 8601 format


Event Description
createdDate The date/time when the order was created in Shipwire.
processedDate The date/time when the order was prepared for warehouse submission. This happens just prior to submission. A processed order will have been merchant-billed.
submittedDate The date/time when the order was submitted to a warehouse for processing.
completedDate The date/time when the order has been packed. Tracking information is available and the order is ready for carrier pickup.
expectedDate The date/time when the Shipwire platform expects the order to be delivered, based on the specific carrier/method shipping service level estimates.

Forgot your password?