Getting started

Use the Shipwire API to deliver a world-class e-commerce experience customized to your business needs. Our technology lets you create flows that are both tightly integrated and highly automated. Our API consists of two main parts:

• REST API (see API Resources in the menu to the left) for creating, updating, deleting and getting details on a variety of resources on demand.
• Webhook topics that may be subscribed to in order to get real-time push notifications to your webserver of events you are interested in.

API Resources

Order API: The Order API is used to create outbound B2C orders as well as reveal shipment details (shipping box dimensions, contents, tracking…)

Purchase Order API: The Purchase Order API is used to create POs (offers from retailers to purchase items from you for shipment to their customers or their DCs/stores) in our system. If you accept the terms, you may approve the PO, and one or more fulfillment orders will be created to complete the shipment. This API introduces additional fields that are relevant for orders to retailers, such as retailer/supplier SKUs and product descriptions for use on custom packing lists and B2B shipping/delivery windows.

Tip: If you think you might need these features at some point, you may wish to exclusively use the PO API to create orders, to make it easier to add this functionality later.

Stock API: The Stock API is used to get real-time information on stock levels across warehouses.

Rate API: The Rate API is used to get real-time shipping estimates during the checkout process on your website.

Product API: The Product API is used to create and edit products, and get information on existing products.

Receiving API: The Receiving API is used to create, edit, cancel, and get information on receivings (shipments from your supplier to our warehouses).

Return API: The Return API is used to create returns for existing orders and get information on existing returns.

Address Validation API: The Address Validation API is used to validate ship to addresses, so you can correct address errors during checkout.

Webhook API: The Webhook API is used to create, edit, and delete webhook topic subscriptions. See our list of webhook topics and webhook requirements in our Webhooks Guide.

Business Reports: The Business Reports API is used to manage subscriptions to available reports and for downloading the same.

Beta sandbox

You can start testing your Shipwire integration and our various API’s by requesting a sandbox account in our Beta environment. Please reach out to your Account Manager or Sales Representative to obtain access credentials.  

Production and Beta API URLs

TYPE	SHIPWIRE ACCOUNT LOGIN	API URL
Production	shipwire.com	https://api.shipwire.com/
Sandbox	beta.shipwire.com	https://api.beta.shipwire.com/

Authentication

The Shipwire API authenticates clients using bearer tokens generated for API users. The Shipwire administrator can generate up to two keys (i.e., ‘tokens’) from the “Users and Roles” page in Shipwire. The administrator can refresh/expire the tokens as well. For more details about the API User role, you can view this link. To authenticate your API calls, include your Shipwire Key string in the Authorization header. For example, to authenticate your request when accessing the stock resource on your production account, send an HTTP request like the following:

 
GET  https://api.shipwire.com/api/v3/stock 
Authorization: ShipwireKey YOUR_SHIPWIRE_KEY_HERE 

If your request is authenticated by the server, it will reply with the appropriate data for the request you made. Otherwise, it will reply with a ‘400 Unauthorized’ status. Note: Shipwire’s API protects merchant and customer information by encrypting communication through SSL. As such, all Shipwire API endpoints use the HTTPS protocol.

Meaning of HTTP Status Codes

If you run into trouble using Shipwire API, check the response messages for error descriptions and possible solutions.

STATUS	CATEGORY	DESCRIPTION
2xx	Request Was Understood	The action was successfully received and understood. Note that this does NOT mean that the expected operation was completed. See “Handling Errors” below for important details.
4xx	Client Error	The request contains bad syntax or cannot be fulfilled. This means there is a problem with the request. The problem must be resolved before re-submitting the request.
5xx	Server Error	The server failed to fulfill an apparently valid request. This means there is either a temporary problem or a bug. The request may be re-submitted later. If it continues to fail, please share the JSON request body with your Shipwire representative.

Specifying Dates

The Shipwire API expects ISO 8601 format dates for all values provided in date fields. This follows the format: YYYY-MM-DDThh:mm:ss.sss±hh:mm Example: 1999-12-31T23:59:59-07:00 (December 31, 1999 at 11:59:59 PM in Pacific Time, -7 hours from GMT) For fields where the time is not necessary, you may simply provide the date, and we will assume you meant that date at 12 midnight, Pacific Time. Use this format: YYYY-MM-DD

Specifying Shipping Service Levels

Many clients use our rate API to show shipping options in their shopping cart checkout process, in which case, when creating the order, you would pass the “carrierCode” given in the rate API response that the customer chose. Alternately, if you would like to offer flat rate shipping in your cart, you can pass a service level code (“serviceLevelCode”) from the below table, and we will pick the least cost shipping service for that level to the given address. If neither “carrierCode” nor “serviceLevelCode” are included, we will default to the least cost method.

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.

Handling errors

Shipwire API uses status codes to indicate some kinds of errors (e.g. 401 and 403 for authentication issues), but many kinds of errors will be returned with 2xx status codes. For all POST and PUT operations, please ensure that your application checks the response body for an errors and/or v4Errors element. If included, this means that the resource was NOT created/updated, and more details on the reason will be included under that element. The listed errors must be fixed and then you may retry. We strongly recommend that you store and display these errors to the business users of your integration so they can be resolved without the help of a developer, if possible. For example, here is a failed POST to the purchaseOrders API. In this case, an externalId was passed that had already been used. ExternalIds, if passed, must be unique. The PO was not created, as indicated by resource.total = 0, as well as the appearance of “errors” and “v4Errors” objects in the response.

  {
      "status": 200,
      "message": "Successful",
      "errors": [{
          "type": "error",
          "code": "submitFailed",
          "message": "Additional validation errors occurred. To get a
          thorough list of validation errors please look into the‘ v4Errors’ property." 
      }],
      "v4Errors": {
          "0": {
              "externalId": {
                  "rules": {
                      "uniqueExternalId": {
                          "message": "Duplicate External ID 123 already exists in the system.",
                          "cause": "DUPLICATE_IN_SYSTEM_ERROR",
                          "ruleValue": {
                              "uniqueExternalId": null
                          }
                      }
                  }
              }
          }
      },
      "resourceLocation": "https://api.shipwire.com/api/v3/purchaseOrders?offset=0&limit=20",
      "resource": {
          "offset": 0,
          "total": 0,
          "previous": null,
          "next": null,
          "items": []
      }
  }
   

Navigating through subresources and pages

The Shipwire API was built to be efficient, allowing you to retrieve only the information you require, and no more. Depending on your needs, you may need to make multiple API calls to retrieve all the information you require.

Resource Location Links

By default, subresources consisting of arrays (most commonly: items, trackings, pieces, extendedAttributes) simply have a “resourceLocation” link, providing the URL that may be called to retrieve the items under that subresource. Here’s an example:

GET https://api.shipwire.com/api/v3/orders/628911556
    
{
    "status": 200,
    "message": "Successful",
    "resourceLocation":"https://api.shipwire.com/api/v3/orders/628911556",
    "resource": {
    "externalId": null,
    "orderNo": "123",
    …
    "items": {
        "resourceLocation":
        "https://api.shipwire.com/api/v3/orders/628911556/items?offset=0&limit=20"
    },
}

If you would like to see the items for this specific order, make a call to the given URL under “resourceLocation”. Use expand=all and "next" links to retrieve all items Instead of the above, most developers use the “expand=all” parameter in their API call, which will show you the first 20 items for each of the subresources consisting of arrays. In many cases, this will show everything needed. Here’s an example for the receivings API, looking at a receiving that has 33 different items on the receiving:

GET https://api.shipwire.com/api/v3/receivings/628397263?expand=all
{
    "status": 200,
    "message": "Successful",
    "resourceLocation": "https://api.shipwire.com/api/v3/receivings/628397263",
    "resource": {
      "externalId": null,
      "orderNo": "123",
      "id": 628397263,
      ...
      "items": [
        {
          "resourceLocation": "https://api.shipwire.com/api/v3/receivings/628397263/items?expand=all&offset=0&limit=20",
          "resource": {
            "offset": 0,
            "total": 33,
            "previous": null,
            "next": "https://api.shipwire.com/api/v3/receivings/628397263/items?expand=all&offset=20&limit=20",
            "items": [
              {
                "resourceLocation": "https://api.shipwire.com/api/v3/receivings/628397263/items/1024138759",
                "resource": {
                  "sku": "ABC123",
                  "quantity": 1,
                  "id": 1024138759,
                  "productId": 516283696,
                  "productExternalId": null,
                  "orderId": 628397263,
                  "orderExternalId": null,
                  "expected": 10,
                  "pending": 0,
                  "good": 10,
                  "inReview": 0,
                  "damaged": 0
                }
              }
            ]
          }
        }
      ]
    }
  }

You’ll see the first 20 items in this response. To get the next page, call the URL given in the “next” link. Since we know the total items is 33, we know this next page will show us items 21-33 (next page of up to 20). This next page is the last in this particular case, which will be clear because “next” will be null on that page. This behavior can make it easy to get all items under a subresource by simply calling all “next” links until you reach “next” null, adding the items to the object model on your end.

Subresource limits

On any of the subresource calls, you may change the limit parameter to reduce the number of calls that you need to make. In the previous example, the “next” link was:

"next":"https://api.shipwire.com/api/v3/receivings/628397263/items?expand=all&offset=20&limit=20"

You can change this to something like:

"next":"https://api.shipwire.com/api/v3/receivings/628397263/items?expand=all&offset=20&limit=100"

When you make this call, subsequent “next” links for more pages (if any) will inherit this larger limit parameter. Most subresources can handle a limit of 200, but higher limits have the potential to cause 500 internal server errors. For this reason, we ask you to avoid going higher.

Additional Assistance

If you need additional assistance, visit our support page or contact us.