Table of Contents
Updated by Colin
Welcome to the ShipStream Plugin Fostering Program!
A ShipStream Plugin is a piece of code that operates directly within the ShipStream WMS to integrate with third-party systems. As such, it must meet basic code quality requirements and be designed to operate in a way that is secure, scalable, stable, user-friendly and low-maintenance.
The Plugin Fostering Program is setup to allow third-parties to develop ShipStream plugins which are then "donated" to ShipStream and "adopted" by ShipStream as officially supported plugins. This allows the third-party to perform the bulk of the initial development and then hand it over to ShipStream for long-term maintenance so that the plugin is always up-to-date with the latest version of ShipStream. This also allows the plugin to take advantage of the features that the ShipStream plugin system provides such as easy end-user setup, user-friendly error handling, zero-latency API access and more.
Please read the program outline below and if you're interested in collaborating on a ShipStream plugin just send us an introduction to firstname.lastname@example.org to get started!
A plugin development will follow these basic stages:
- Scope Discovery
- Review and Acceptance
Step one is to know what you are setting out to accomplish and make sure your plans for the plugin are compatible with ShipStream's vision for it's plugin library. There is no single set of requirements that fits all plugins as the scope depends entirely on your business needs and the capabilities of the third-party system. The ShipStream plugin system is not limited to a single type of integration, but in general the most common integrations will:
- Update "Advertised" inventory in the third-party system by SKU using either periodic sync, events or a combination of both.
- Import orders periodically or on-demand for fulfillment (e.g. only orders that are paid and/or approved).
- Push back tracking numbers and other information for completed shipments.
Plugins could deviate significantly from this mold. Understanding the capabilities of both systems and the needs of the business are key here. Clearly communicate the scope of work you intend to tackle and we will work with you to make sure the concepts are sound and that we're on the same page before the heavy lifting begins.
List all of the requirements of the plugin before starting development and submit these to us for review and approval. The requirements will be used in the Review and Acceptance step to ensure that the plugin does what it was intended to do. The requirements may change but at least 90% of the implementation specifics should be discovered and determined during the Scope Discovery and Requirements process.
For example, you may need to research the third-party system's capabilities for updating inventory and determine:
- What identifier should be used on each end to associate ShipStream products to the third-party inventory items?
- How are in-progress orders accounted for in the inventory amounts?
- What workflow can be used to synchronize the inventory while minimizing potential for race conditions?
Provide a list of requirements to ShipStream just like you would provide to a third-party were you paying them to develop the integration for you. This will give us an opportunity to make sure your plugin plans are on the right track before you begin, provide pointers and valuable feedback, and set the stage for development.
The ShipStream Merchant Plugin Middleware is a lightweight and simplified development environment that "mocks" the full ShipStream WMS code environment. It allows you to develop the plugin code which will run in the native ShipStream WMS environment without needing the full ShipStream WMS source code and local development environment. Code that works in the middleware environment should work exactly the same in the production environment, only with all of the benefits that ShipStream plugins provide such as user-friendly error reporting and resolution, easy web-based setup and configuration for any number of Merchants, and zero-latency API access.
ShipStream will provide you with the source code for one or more reference plugins which you should use as a reference for code organization, code style and design conventions.
Be sure to read ahead to Review and Acceptance to keep the review requirements in mind during development.
Review and Acceptance
Once your integration is working with a proof of concept installation built on the Middleware platform we will review and test your code and make sure it meets the standards to be included into the official plugin library.
Here are some general guidelines for plugin authoring to keep in mind during development for plugins that you desire to be accepted as official ShipStream-supported plugins:
- The plugin code including all comments must be written in English.
- Your plugin code should not make any reference to companies other than ShipStream and the third-party with which the plugin integrates.
- Include a README.md file describing the requirements, how the plugin works, why it is designed the way it is, etc. In general, document anything relevant to a fresh set of eyes which may be reviewing, testing, deploying or maintaining the plugin code in the future. Sections of the README should include: Scope, Requirements, Workflows, Setup Steps, Technical Resources, Technical Contacts.
- Your plugin code should not contain, within reason, any hard-coded information or logic that might apply only to your company, such as API keys, unique ids, or configuration decisions. For example if the third-party platform supports a broad range of SKU formats but your company employs a very specific SKU format, the plugin should not be designed to operate only with your more specific format when other users obviously may wish to use a different SKU format.
- Your plugin code and README.md must comply with all legal and licensing requirements in your jurisdiction and not contain any copyrighted or copy-left material for which you cannot freely convey to ShipStream.
ShipStream will review your work and provide feedback, make modifications or request changes until we are satisfied with the quality of the plugin.
Once your plugin has passed review and been merged into ShipStream it will become available in your installation as a Plugin. We will activate your Plugin and configure the global settings, if necessary. Finally, you and your Merchants will be able to setup Subscriptions with your new plugin at-will!