Table of Contents
Updated by Colin
ShipStream's OpenMage / Magento plugin provides a direct integration with Magento-based shopping carts which provides the following functionality:
- Import Sales Orders from Magento depending on the order status
- Synchronize available inventory from ShipStream to Magento
- Update shipment tracking information in Magento
This plugin uses push notifications in both directions so that updates occur immediately and efficiently rather than relying on a slow or inefficient polling mechanisms, eliminates potential for race conditions with a basic locking mechanism for order submission and performs accurate inventory level adjustments using a single transaction within Magento's database.
The following shopping carts are supported by the OpenMage / Magento plugin:
- Magento Community Edition 22.214.171.124 or newer
- Magento Enterprise Edition 1.11 or newer
- OpenMage LTS, Mage One or other compatible fork
The only prerequisite for setting up the plugin is to install the open source ShipStream OpenMage Sync Extension. This extension does the following:
- Exposes additional API endpoints to facilitate a simple two-way communication setup and accommodate the advanced synching strategy that is not possible with the API endpoints provided by Magento out of the box
- Adds two new Order Statuses to facilitate straightforward and transparent order synchronization.
- Adds a cron job to do a flash inventory sync every hour.
- What functionality does this extension add to my OpenMage/Magento store?
- Why is this required? Doesn't OpenMage/Magento already have an API?
- What is the point of the new statuses?
The ShipStream OpenMage Sync Extension can be installed using Composer, modman, or extracting a zip/tar file. See the Installation section of the README for more information.
After the extension files are installed to complete installation:
- Be sure to flush the Magento cache to ensure the extension is activated. Click System > Cache Management > Flush Magento Cache.
- Update your User Roles if necessary to add the System > Configuration > ShipStream Sync Section resource so you can access the configuration section later. If you are an Administrator this step is not necessary.
- Log out of Magento and log back in (this refreshes the active user's permissions - otherwise you may receive a 404 or Access Denied error when accessing the configuration section)
Once the extension is installed in your Magento shopping cart you will need to create an API Role and API User to use with the ShipStream Plugin Subscription. The API User's "User Name" and "API Key" will be needed to complete the setup in ShipStream.
- Navigate to System > Web Services > SOAP/XML-RPC - Roles
- Click Add New Role
- Provide the name ShipStream and confirm your current admin password
- Click the Role Resources tab and select the resources listed below
- Sales / Order / Change status, add comments
- required to set the order status to Complete after fulfillment
- Sales / Order / Retrieve orders info
- required to get basic order information pertinent to fulfillment
- ShipStream Sync
- use the custom API methods added by the ShipStream Sync extension
- Click Save Role
- Navigate to System > Web Services > SOAP/XML-RPC - Users
- Click Add New User
- Fill in the form fields choosing a secure API Key and note the "User Name" and "API Key" for later use
- Click the User Role tab and select the "ShipStream" role created in steps 2 through 5
- Click Save User
You may wish to change the default configuration in the System > Configuration > Services > ShipStream Sync section to fit your needs.
You are now ready to create and configure a Plugin Subscription in ShipStream.
- Navigate to System > Integrations > Plugin Subscriptions
- Click Add New Subscription
- Select the appropriate Merchant
- Select the OpenMage/Magento 1 plugin
- Enter the following information in the Plugin Configuration:
- Set Active to Yes if you are ready for the plugin to immediately become active after saving
- The SOAP API URL is typically the Magento admin site base url plus
- The SOAP/XML-RPC User Name is the "User Name" of the API User you created in the Setup steps
- The SOAP/XML-RPC API Key is the "API Key" of the API User you created in the Setup steps
- The Auto-Fulfill Order Status determines which order statuses will be automatically imported into ShipStream. Choose "Processing" to import orders with no user-intervention or "Ready to Ship" to require a Magento user to update the status manually.
- The Custom Auto-Fulfill Statuses may be used if you have a custom order workflow with your own custom order statuses.
- The Magento shipping method codes for FedEx, UPS and USPS match the ShipStream shipping method codes, but if you need to translate other shipping methods from Magento to ShipStream the Shipping Method Translation config will allow you to do so.
- The Order Transform Script allows you to specify more advanced modifications to the new order data before the order is created using the Magento order data.
- Optionally specify a Sync Orders Since date if you would like to pull in existing orders using the Sync Orders button after the subscription is saved.
- Click Save Subscription
At this point the plugin will attempt to authenticate with the Magento store and provide a callback url to the Magento store to establish two-way communication. If the plugin is Active it will start to sync inventory and order data automatically.
The ShipStream Sync extension adds three new Order Statuses:
- Ready to Ship - the order is cleared to be submitted to ShipStream - this is optional and not used if the Auto-Fulfill Order Status is "Processing"
- Failed to Submit - there was an error submitting the order to ShipStream
- Submitted - the order was successfully submitted to ShipStream
Processing vs Ready to Ship
In Magento an order will automatically advance to Processing once it has been fully invoiced. If you wish to auto-fulfill orders in this status you can choose Auto-Fulfill Order Status: Processing and the plugin will automatically import these orders. If you want more manual control or have your own custom automated workflow you can choose another status. The Ready to Ship status is added for this purpose but you could also add your own. This diagram depicts the order states if you were to use Auto-Fulfill Order Status: Ready to Ship:
To manually advance an order to Ready to Ship status use the Add Order Comments block on the order page to choose the Ready to Ship status and click Submit Comment.
Once the order has been imported the order status will advance to Submitted with a comment indicating the ShipStream Order number.
Once an order is successfully submitted to ShipStream (as indicated by the Submitted order status in Magento), any time a new Shipment in ShipStream advances to Packed status a corresponding Shipment will be pushed to Magento complete with tracking information. As usual in Magento once all order items are Shipped the order status will automatically advance to Complete.
Therefore, one can assume that any orders that are in Submitted status in Magento have been transmitted to ShipStream successfully but have not yet been packed out and any orders that are Complete in Magento have been not only submitted to ShipStream but also picked and packed.