shipwire-node-client

Shipwire API Client for Node.js

Getting Started

Installation

// using NPM
$ npm install --save shipwire-node-client
 
// using Yarn
$ yarn add shipwire-node-client

Constructor

const Shipwire = require('shipwire-node-client')({
  username: '<username>',
  password: '<password>',
  beta: false
});
 
// you could also create the token yourself and send that in instead
const Shipwire = require('shipwire-node-client')({
  token: new Buffer.from('<username>:<password>').toString('base64'),
  beta: true
});

The Shipwire constructor takes an object with up to four fields:

• token - Authentication method - a base64-encoding of your Shipwire username:password string. This is your username, followed by a colon (:), followed by your password.
• username - Authentication method - requires password as well - your Shipwire username
• password - Authentication method - requires username as well - your Shipwire password
• beta - Defaults to false - determines whether the host will be api.beta.shipwire.com (if beta evaluates to true) or api.shipwire.com (if beta evaluates to false)

If a valid authentication method is not passed in, an error will be thrown.

API

Syntax

Each Shipwire API endpoint can be accessed through the Shipwire object returned by the constructor. The syntax is

Shipwire.<resource>.<method>(<params>)

For example, to retrieve a list of returns the appropriate call would be:

Shipwire.returns.list(); // this method needs no params

Parameters

All endpoints can take parameters and many require them. The parameters an endpoint accepts are first a series of strings that will be matched to create the path (more below). The last parameter may be an Info object, which describes the querystring and the body of the request.

const Info = {
  body: {...}, // the body to send with the request
  pdf: Boolean, // determines whether to accept a pdf response. defaults to False
  query: {...} // the query field will be querystringified and appended to the path
};

The Info object is optional in some cases. If included, it can have as few as 0 and as many as all of the fields shown above.

Path Replacement

All parameters sent to a method, except for the last one if it is an object, will be interpreted as strings for the purpose of path replacement. Shipwire endpoints can require specific ID(s) to complete: /api/v3/orders/:id, the endpoint for retrieving a specific order, requires an order ID in the path. When this endpoint is called, all string parameters will be substituted in for required IDs in the path in the order provided.

// will call '/api/v3/orders/order_id'
Shipwire.orders.get('order_id');
 
// will call '/api/v3/orders/order_id' and ignore 
// 'Simon' and 'Garfunkel' since there is only 1 thing in the path to replace
Shipwire.orders.get('order_id', 'Simon', 'Garfunkel');

Promises

All endpoints return a promise.

const Info = {
  body: {
    orderNo: "foobar1",
    externalId: "rFooBar1",
    vendorId: "567"
  },
  query: {
    extra: "information",
    for: "querystring"
  }
};
 
// will call '/api/v3/orders/id_of_order?extra=information&for=querystring'
Shipwire.orders.modify('id_of_order', Info).then(res => {
  console.log(res);
}).catch(err => {
  console.error(err);
});

Resources and Methods

• carriers
  • list([Info])
  • get(carrierId)
• containers
  • list([Info])
  • create(Info)
  • modify(containerId, Info)
  • get(containerId)
• orders
  • list()
  • get(orderId)
  • create(Info)
  • modify(orderId, Info)
  • cancel(orderId)
  • contents(orderId)
  • holds(orderId [,Info])
  • getTrackings(orderId)
  • createTracking(orderId, Info)
  • invoice(orderId)
  • packingList(orderId)
  • shippingLabel(orderId)
  • splitOrders(orderId)
  • pieces(orderId)
  • attributes(orderId)
  • returns(orderId)
  • clearHold(orderId)
  • markProcessed(orderId)
  • markSubmitted(orderId)
  • markComplete(orderId)
  • generateLabels(Info)
  • labelStatus(jobId [, Info])
  • generatePackingList(Info)
  • packingListStatus(jobId [, Info])
• products
  • list([Info])
  • create(Info)
  • modifyGeneral(Info)
  • modifySpecific(productId, Info)
  • get(productId)
  • retire(Info)
• purchaseOrders
  • list([Info])
  • get(purchaseOrderId [, Info])
  • create(Info)
  • modify(purchaseOrderId, Info)
  • cancel(purchaseOrderId)
  • hold(purchaseOrderId)
  • clearHold(purchaseOrderId)
  • listHolds(purchaseOrderId [, Info])
  • items(purchaseOrderId)
  • trackings(purchaseOrderId)
  • orders(purchaseOrderId)
  • attributes(purchaseOrderId)
  • approve(purchaseOrderId)
• rate
  • oldCreate(Info)
  • create(Info)
• receivings
  • list([Info])
  • create(Info)
  • get(advanceShipNoticeId [, Info])
  • modify(advanceShipNoticeId, Info)
  • cancel(advanceShipNoticeId)
  • cancelLabel(advanceShipNoticeId)
  • holds(advanceShipNoticeId [, Info])
  • instructions(advanceShipNoticeId)
  • attributes(advanceShipNoticeId)
  • items(advanceShipNoticeId)
  • shipments(advanceShipNoticeId)
  • trackings(advanceShipNoticeId)
  • labels(advanceShipNoticeId)
  • complete(advanceShipNoticeId)
• reports
  • list([Info])
  • get(reportId)
  • getSubscribed([Info])
  • getNotSubscribed([Info])
  • generated([Info])
  • subscribe(reportId, Info)
  • unsubscribe(reportId)
  • listFrequencies()
  • listSubscribers()
• returns
  • list([Info])
  • create(Info)
  • get(returnId [, Info])
  • cancel(returnId [, Info])
  • holds(returnId)
  • contents(returnId)
  • tracking(returnId)
  • labels(returnId)
  • markComplete(returnId)
  • generateLabels(Info)
  • labelStatus(jobId [, Info])
• secret
  • list()
  • create(Info)
  • get(secretId)
  • delete(secretId)
• stock
  • list([Info])
  • adjust(Info)
• vendors
  • list([Info])
  • create(Info)
  • modify(vendorId, Info)
  • get(vendorId)
  • retire(vendorId)
  • attributes(vendorId)
• warehouses
  • list([Info])
  • create(Info)
  • modify(warehouseId, Info)
  • get(warehouseId)
  • retire(warehouseId)
  • containers(warehouseId)
  • carriers(warehouseId)
  • addCarrier(warehouseId, Info)
  • removeCarrier(warehouseId, Info)
• webhooks
  • list()
  • create(Info)
  • get(webhookId)
  • modify(webhookId, Info)
  • delete(webhookId)

Contributing

If you like this project, we'd love to have your help. Contributing doesn't necessarily mean writing code though. You can also help out by:

• Opening issues on bugs you find or new features you'd like to see
• Joining discussion on issues and pull requests
• Helping write documentation i.e. fleshing out the Methods

Updating NPM

Generally, the workflow for updating the NPM package is as follows:

1. (Optional) Open an issue and describe what you will be trying to fix: a specific bug or a new feature
2. Clone the repo to your local machine
3. Create a new branch (pick a name that clearly describes the intent)
4. Commit changes to the new branch and push to origin
5. Open a pull request with a clear description of the change - allow some time for feedback
6. Once there's a general consensus, merge the PR into master and update the npm package as needed

To Do

• Handle (throw errors on) empty tokens in constructor