The ShipStation Integration for Miva allows you to quickly and easily connect your Miva store to your ShipStation account. This allows you to pull orders from Miva into ShipStation for label generation and fulfillment. Once an order has been shipped from within ShipStation, the tracking number and shipment information is then pushed back into Miva so the end customer always has the most up to date information and Miva has to most accurate shipping history for every order.
This integration uses the latest ShipEngine Connect APIs and is intended to replace the existing Miva Module for ShipStation. If you are currently using ShipStation and Miva, please review our Migration Guide.
The first step is to download the Miva Shipstation configuration file from the app store here: https://apps.miva.com/shipstation.html
This is an XML file which you will upload to your store under Setting -> Data Management -> Import Data and Settings in XML Provisioning Format
Drag n drop the file or select "Choose File" to select the shipstation_setup.xml file. It should take a few seconds to process, and you'll see a "Import of shipstation_setup.xml complete" message.
This configuration file creates the following in Miva:
ShipStation talks to Miva using our JSON API. An API token needs to created specifically for ShipStation to use and with the correct permission levels.
In Miva, navigate to Settings -> Users Management -> API Tokens and click Add API Token
Name: This can be anything you like, but make it descriptive for the system it will be used in for example "ShipStation API Key"
Endpoint URL: Copy this value and save it for later. You will need it to enter into ShipStation configuration.
Access Token: Copy this value and save it for later. You will need it to enter into ShipStation configuration.
Allowed IP Addresses – Since we don't have a dedicated range of IPs which Shipstation uses, you'll need to whitelist all IPs. Note, Miva will give you a warning about doing this since it is less secure.
Signature: Copy this value and save it for later. You will need it to enter into ShipStation configuration. Note: This value is only displayed the first time you create the token. If you need to change it you'll have to click the generate button to create a new one and update this new value in ShipStation.
Timestamp: This should the default value of 30 seconds.
Click Save to create the token
Once the token has been created you'll need to add the right functions to the token so it has the appropriate permissions to request data. From the batch list select the checkbox for the API to toke and click the Functions button.
There are 8 functions you will want to give permissions for this API Token
When you click Add Function, the first column will let you select if the function operates at the domain level or store level. All these functions are store level functions. You will need to select your store.
Once you have your Miva API Token setup and the XML configuration file imported, the next step is to connect Shipstation to Miva.
Login into your ShipStation account. At the top right click on the settings Icon (Sprocket)
Then click Selling Channels -> Store Setup. From this screen click Connect a Store or Marketplace
Search for Miva. Its likely you'll see two integrations. Miva Merchant and Miva Merchant (JSON API). Make sure you select the one for the JSON API.
This will bring up the Connection Form for Miva
Store Code – This is your Miva store code and can be found under Settings -> Store Settings in Miva
JSON API Endpoint – Copied from your Miva Admin API Token
JSON API Signature – Copied from your Miva Admin API Token
Currency Code – Select from a list of currencies ShipStation supports. This should match the currency you have selected in your Miva Store.
Image Type Code – This is the image type code of the image you want ShipStation to pull from when it is pulling in orders. Most of the time this will be "main" but this can be updated to any image type you use in your Miva Store. To see your image type codes in Miva go to User Interface -> Global Settings -> Image TypesOrder Workflow Queue Code – The XML configuration file creates this Queue with a code of "shipstation_orders"
Order Custom Field Mapping
This section is optional but allows you to map custom fields setup in Miva to those setup in ShipStation.
The XML file creates these custom fields in Miva what can be optionally be used. However, if you already have a field that is used to collect things like order notes during checkout, you can map that to the ShipEngine/Station custom field.
Here is a full list of available Custom Order fields to Map:
Important: All the date fields must use the RCF2822 format (YYYY-MM-DD hh:mi:ss) including: shipstation_deliver_by_date, shipstation_hold_until_date, shipstation_ready_to_ship_date, and shipstation_ship_by_date
Enable Order Acknowledgement – This is a checkbox to tell ShipStation if you want it to push back Order Acknowledgements back to Miva.
Once the store is successfully connected you should see a status of a green checkbox like this:
With the Order Workflow Miva will automatically put all new orders into the "ShipStation Orders To Download" Queue as long as they pass the conditions configured which are:
If you want to manually place an order into the ShipStation (or remove an order) you can do that from the Orders Batch list of Order Detail Screen.
Order Batch List
There is a custom field identifying which orders are in the ShipStation Orders to be Downloaded Queue. To see it on the batch list, click the batch list show/hide columns icon, expand Show/Hide Custom Field and select "Shipstation- Orders To Download"
Once the column is visible on the batch list you can edit it individually or in bulk (using Column Edit) to add or remove orders from the Queue.
Order Detail Screen
To add an order to the queue from the order details screen click on Order Workflows then check or uncheck the box for "Shipstation – Orders To Be Downloaded"
Once Miva is connected to ShipStation, ShipStation will automatically pull orders from the Queue you have setup in Miva. If you need to force a sync of orders you can click the refresh button at the top right in ShipStation
This allows you to update all connected stores or you can click the refresh icon next to each store.
Based on the payment status in Miva, the order will get imported into ShipStation in the following Payment categories.
Net_capt < Total=AwatingPayment
Net_cap – total = 0 , Order Marked As Paid in ShipStation
Pending, processing, partially shipped = AwaitingShipment
Shipped and not backordered = Completed
Canceled = Canceled
Backordered = onHold
Anything Else = PendingFulfillment
The Order Item SKU field is the master identifier for products. If the order item in Miva has a SKU it will be mapped to ShipStations SKU field. This value will automatically be the variant SKU in Miva if inventory variants are being used.
If an order item SKU field is empty/blank, then the product code will be used and mapped to the ShipStation SKU field.
ShipStation Order Item Example
Miva Order Item Example
Notice in the example above, the Product Code is "shirt" but the SKU field is that of the specific variant (small shirt) and that is the value that is passed into ShipStation for fulfillment.
As long as an order in Miva is not in a Shipped/Returned state changes to the order will get correctly synced to ShipStation if you manually add it back into the ShipStation Queue.
Let's say a customer placed an order and it was pulled into ShipStation awaiting Fulfillment. 10 minutes later they call up and ask to change the quantity of an item from 1 to 3. The customer Service Rep can update the order in Miva and manually add the item back to the ShipStation Queue. At the next sync, ShipStation will update this order with the correct Quantity and highlight the quantity change in yellow
Gift Message - In the connection form configuration for the store, if you have "gift message" mapped to a custom order field in Miva and this value is set for the order, the flag for "gift" will be set for the order in ShipStation. Note: ShipSation only has an order level flag for gift, not an item level flag.
Note Mappings - There are two types of note mappings. If the order has any Order level notes, those will get sent down and mapped into the "Internal Notes" section of ShipStation notes. This happens automatically and there is nothing you need to map in the connection form for this to work. Keep in mind that only notes created by an admin user will be included here. Automated notes that Miva creates based on actions that happen on the order will be be sent.
The second note mapping is for the "Additional Handling" field. If this custom field is set in the connection form during setup, the notes will be included in the "Note From Buyer" field.
The following pagination rules are used for API calls made to Miva around pagination
Sales Order Export = 50 Orders Per Page
Shipment Notification: 10 Shipments Sent in a single API call
Acknowledgements Orders: 25 Acknowledgements Sent at a time
These values are built into the integration and cannot be change but they will give you an idea of the number of API calls being made as part of the integration.
There are custom product fields which will get synced to Shipstation if these values are populated in Miva. These are located under the ShipStation tab on the product edit screens.
Note: SKU and Fulfillment SKU are automatically mapped to the SKU or Product Code in Miva.
When a label/tracking number is created in ShipStation for a Shipment it will automatically get pushed back to Miva. Shipstation will create the shipment in Miva, and mark it as shipped. This will cause the Shipment Shipped Email in Miva, if configured.
If you are manually marking a shipment as shipped for some reason, ensure the Notify Marketplace checkbox is checked (default)
ShipStation allows you to split an order into multiple shipments. There are two type of split shipments
Example: let's say a customer buys 10 of an item. However, you only have 5 to ship. You can split this item into two-line items in ShipStation. But once either of the two new line items are shipped, Miva will mark the original 10 as shipped in Miva which means it won't get split into two line items first.
ShipStation has a "Combine Shipment" feature. It allows the user to merge two different orders into a single order/shipment. While you can do this in ShipStation this action is not supported by the integration and will prevent you from pushing back up Tracking Numbers to Miva for that new Order/Shipment. This is due to a limitation in how this function operates. When combined the previous order ids and line ids are not longer available in the newely created order/shipment preventing any updates back to Miva.
ShipStation does not have a concept of a Kit. However, the integration will pass through any kit parts including their part SKU (or product code if SKU is not set) and quantity. These are located under the Description section with the "Parts:" Prefix
Here is how the Kit looks in Miva
The integration supports sending order acknowledgments back to Miva. This is added protection in case of a communication error when orders are being downloaded. To use this feature ensure you have the checkbox checked in the connection form:
Once checked, this feature automatically works. There is no additional configuration other than ensuring the Workflow in Miva is setup for your needs.
The default XML does the following:
Note: The Order Acknowledgement API call is only every made once. So, if you manually add an order back into the ShipStation queue, the Order Acknowledgement will not be sent a second time. Instead, each time the order is pulled from the Shipstation queue, the integration will automatically remove it from the Queue every time regardless of if order Acknowledgement is checked or now. The acknowledgement allows for additional visibility just as adding order notes and moving it into an archive queue for historical tracking.
For existing customers using the older module based intrgration, below are the steps to take to setup the new integration and remove the old version.