Create Orders via the Orders API
Use the ShipWorks API to send order information directly to ShipWorks and to push shipment details to your order source.
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
-
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.)
-
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.
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.)
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.
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. |
|
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. |
|
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_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.
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" }
-
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.
Have a comment to share about this article? We'd love to hear from you. You must be logged in to your Support Portal account to leave a comment.
Comments
1 comment
There was an update to the Callback HMAC Secret Key requirements. It is no longer an optional field and is required if uploading shipment details are needed.