Create Orders via the Orders API

Background

Use the ShipWorks API to send order information directly to ShipWorks and to push shipment details to your order source.

First Things First

To use the ShipWorks API, you will need to be on a ShipWorks plan that includes access to the ShipWorks Hub.

To use the ShipWorks API, you will need to:

Generate a ShipWorks API key
Create Order Source(s): At least one order source is required
Ensure that you are posting sales orders correctly to ShipWorks

The Process

Go to The Hub and Log In

Open a web browser and go to hub.shipworks.com.
Log in using your ShipWorks account email and password. (This is the same email address and password that you created when setting up your ShipWorks account.)

Generate an API Key

Click on API Settings.
Enter a Description for the API Key that you are generating. Then, click the Add button. (The description is optional. However, it may be useful to add a description so that, in the event you create more than one API Key, it is easy to identify one key from the others.)

The API Key is generated and is displayed in the list of API Keys.

There is a new API key highlighted in the list of keys.

Add an Order Source

You must add at least one Order Source. Please refer to the note regarding Orders Sources in the Create a Sales Order Manually section of this article for more information.

Click on API Settings.
Enter a Description for the Order Source you are creating (Required. 50-character limit).
Enter your Ship Notify Callback URL. (Optional. However, this URL is required when sending shipment information back to the order source. 100-character limit.)
Enter your Callback API Key. (Required. 100-character limit.)

Enter your Callback HMAC Secret Key. (Optional. However, this step is required to send tracking information back to the order source. 20-character limit.)

The order sources dialog is displayed with the callback HMAC secret key field highlighted.

HMAC Verification

When using a Callback HMAC Secret Key, the following code example may be used to verify the HMAC.

import React from "react";
import createHmac from "create-hmac";
import "./styles.css";

const expected =
  "2f3f908cb518c1f13d75968dc0ead2ddf6157c7ae1b70db46bcc3a519669c31c";
const response =
  '{"notifications":[{"notification_id":"1cc52170-fc8d-4b96-850b-038c84206154","order_id":"A8","order_number":"","tracking_number":"9405516555555555566068"}],"auth":{"order_source_api_code":"ordersource-api","api_key":"foo"},"transaction_id":"1cc52170-fc8d-4b96-850b-038c84206154"}';
const secret = "YOURHMAC";

var hmac = createHmac("sha256", Buffer.from(secret));
hmac.update(response); //optional encoding parameter
const digest = hmac.digest("hex"); // synchronously get result with optional encoding parameter

const isEqual = digest === expected ? "true" : "false";

export default function App() {
  return (
    <div className="App">
      <table>
        <tr>
          <td>Expected</td>
          <td>'{expected}'</td>
        </tr>
        <tr>
          <td>Actual </td>
          <td>'{digest}'</td>
        </tr>
        <tr>
          <td>Equal</td>
          <td>{isEqual}</td>
        </tr>
      </table>
    </div>
  );
}

Click the Add () button. ShipWorks generates the Order Source and displays it in the list.

Create a Sales Order - Post

At a minimum, you will need the following information to create your sales order:

external_order_id
order_date
ship_to - (for every sales order item, if any)

NAME	DATA TYPE	DESCRIPTION
external_order_id	string, required	A user-defined order number used to identify an order.
order_source_id	string	The Order Source ID for the order source created earlier in this article.
order_date	date string, (ISO 8601 Standard), required 2019-07-25T15:24:46.657Z	The date that the order was placed.
payment_details	Payment Details	Summary of the payment details for the order. See subtotal, currency, amount below.
subtotal	currency	The amount of the order without taxes or shipping costs.
currency	enumerated string	Defines the type of currency. ShipWorks supports USD.
amount	decimal	The total amount paid for the Order.
estimated_shipping	currency	Shipping amount quoted or collected for the item. See currency, amount below.
currency	enumerated string	Defines the type of currency. ShipWorks supports USD.
amount	decimal	Shipping amount quoted or collected for the order.
estimated_tax	currency	Taxes quoted or collected for the item. See currency, amount below.
currency	enumerated string	Defines the type of currency. ShipWorks supports USD.
amount	decimal	Taxes quoted or collected for the order.
grand_total	currency	Amount charged for the entire sales order. See currency, amount below.
currency	enumerated string	Defines the type of currency. ShipWorks supports USD.
amount	decimal	Amount charged for the entire sales order.
customer	Customer	The customer for the sales order. See name, phone, email below.
name	string	The customer's name.
phone	string	The customer's phone number.
email	string	The customer's email address.
bill_to and ship_to	Bill To / Ship To	The billing and shipping information for the sales order. See email, name, phone, address_line1, city_locality, state_province, postal_code, country_code, address_residential_indicator below.
email	string	The billing email address for the order.
name	string	Name of person.
phone	string	Telephone number.
address_line1	string	First line of address.
address_line2	string	Second line of address.
address_line3	string	Third line of address.
city_locality	string	City
state_province	string	State (two-letter state abbreviation)
postal_code	string	Postal code
country_code	string	Country Code. The two-character ISO country code is required.
address_residential_indicator	string	Yes or No. Indicates whether the address is residential or not.
sales_order_items	Array of Sales Order Items	The line items associated to the order.
line_item_details	Line item details	The details associated to the line items on the sales order.
name	string	Description of the item.
sku	string	The item SKU.
quantity	int	Quantity of the item sold.
is_gift	bool	True or False. Indicates it this item is a gift.
price_summary	Line item price details	This contains price information for this line item; taxes and shipping show what was quoted or charged for this item.
unit_price	currency	Individual price of the item.
ship_to	Ship to information, required	The ship to information associated to the individual item.

EXAMPLE POST - Sales_orders

POST https://proxy.hub.shipworks.com/api HTTP/1.1
Host: proxy.hub.shipworks.com
api-key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "external_order_id": "1111",
  "order_source": {
    "order_source_id": "9ab83300-39ba-4159-96f8-0d0ef6dfcbfa"
  },
  "order_date": "2019-07-25T15:24:46.657Z",
  "payment_details": {
    "subtotal": {
      "currency": "usd",
      "amount": 200
    },
    "estimated_shipping": {
      "currency": "usd",
      "amount": 10
    },
    "estimated_tax": {
      "currency": "usd",
      "amount": 5
    },
    "grand_total": {
      "currency": "usd",
      "amount": 215
    }
  },
  "customer": {
    "name": "Amanda Miller",
    "phone": "555-555-5555",
    "email": "amanda.miller@email.com"
  },
  "bill_to": {
    "email": "amanda.miller@email.com",
    "address": {
      "name": "Amanda Miller",
      "phone": "555-555-5555",
      "address_line1": "525 S Winchester Blvd",
      "city_locality": "San Jose",
      "state_province": "CA",
      "postal_code": "95128",
      "country_code": "US",
      "address_residential_indicator": "yes"
    }
  },
  "ship_to": {
    "name": "Amanda Miller",
    "phone": "555-555-5555",
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "US",
    "address_residential_indicator": "yes"
  },
  "sales_order_items": [
    {
      "line_item_details": {
        "name": "ball of string A",
        "sku": "ball of string A"
      },
      "price_summary": {
        "unit_price": {
          "currency": "usd",
          "amount": 200
        }
      },
      "ship_to": {
        "name": "Amanda Miller",
        "phone": "555-555-5555",
        "address_line1": "525 S Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "country_code": "US",
        "address_residential_indicator": "yes"
      },
      "quantity": 4,
      "is_gift": false
    }
  ]
}

Order Sources: Additional Details

order_source

Note: At least one order source must be created in the ShipWorks Hub. Please see the Add an Order Source section of this article, found above.

Be sure to specify the order_source that you created in the ShipWorks Hub. If more than one order_source exists, you must specify which one you'd like to use in your request.
Third-Party Order Sources

You may only create sales orders via the API with an api order source. Example: You cannot manually create sales orders for your Amazon or Shopify order source. Orders from Amazon, Shopify, or any other third-party order source must be imported by connecting that order source.
Different Shipping Addresses for Different Sales Order Items

You may specify your ship_to address either for the sales order as a whole or for each individual sales order item. If you specify the ship_to address for the sales order, the address will apply across all of the sales order items. You may also specify the ship_to address for the sales order as well as all the items, as long as the addresses are identical.

Sales Order - Ship Notify Callback

ShipWorks sends the following back to your Order Source when the ShipWorks API is configured to upload shipment details.

api-key: the-key-the-user-specified
x-hmac-signature: 7905c256798b34318d8b13d7a0b14204336e5a2174da29cd1b73d0767551de7f
{
  "notifications": [
    {
      "notification_id": "e83ceb7b-3f23-4a4f-aa16-34ef82b1bcec",
      "order_id": "A7",
      "order_number": "",
      "tracking_number": "safddsaf",
      "carrier_code": "other"
    }
  ],
  "auth": {
    "order_source_api_code": "ordersource-api",
    "api_key": "foo"
  },
  "transaction_id": "e83ceb7b-3f23-4a4f-aa16-34ef82b1bcec"
}

Additional Things to Know

SYNCING ORDERS WITH THE SHIPWORKS SOFTWARE

After adding an API Key and Order Source you must log out of and back in to the ShipWorks Software so that ShipWorks can sync with the Hub and so that any new sales orders can be downloaded into ShipWorks.

A new store is created in ShipWorks. Orders created through the ShipWorks API will be associated with this store when downloaded into ShipWorks.

Download Interval

By default, orders will be downloaded into the ShipWorks software every 15 minutes. Modify this setting by going to Manage Tab > Stores > Select the API store > Edit Button > Store Settings.
UPLOAD SHIPMENT DETAILS

By default, ShipWorks is not configured to automatically upload shipment details through the ShipWorks API.

Enable ShipWorks to upload shipment information automatically after a shipment is processed by creating an Action. Please reference the Create a New Action section of the Create an Action for Online Updates article found here.
DELETE API KEYS and/or ORDER SOURCES

You can delete API Keys and Order Sources by clicking the delete button () associated with the key or order source.
- If you delete an API Key or Order Source in The Hub, it does not remove the associated store in the ShipWorks software.
- If you delete an API Key or Order Source in The Hub, it will not remove the associated sales orders from the ShipWorks software.
- If you deleting an API Key or Order source, no future sales order records are created in The Hub or synced with the ShipWorks software.
UNIQUE EXTERNAL_ORDER_ID

The external_order_id must be unique for each Order Source.
CANNOT UPDATE ORDERS

Order details for orders created using the ShipWorks API cannot be updated using the API.
MULTI-PACKAGE SHIPMENTS

Only the parent tracking number for multi-package shipments will be uploaded to the Order Source through the ShipWorks API.

Still Need Help?

Please feel free to reach out to one of our awesome Technical Support Representatives in St. Louis. We are happy to help.

Attachments

Menu