CEVA Logistics has acquired the Shipwire business to become the world's 5th largest logistics provider.

Getting started

Get shipping fast with our API

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.

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 HTTP (Basic) access authentication. The authorization string is generated by Base64-encoding a string containing your Shipwire API username and token. This is your API username, a colon (:), then your API Token. Follow this guide to create an API user.

To authenticate your API calls, just include your Base64-encoded string in the Authorization header. For example, to authenticate your request when accessing the orders resource on your Beta account, send an HTTP request like the following:

 
GET https://api.beta.shipwire.com/api/v3/orders
Authorization: Basic YOUR_BASE64_ENCODED_STRING_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 403 Forbidden 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.

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"</span >

You can change this to something like:


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

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.


Visit our Tutorial page for assistance on order creation and workflows.