• Developer Docs
• Integration Guides
• ShipStation

ShipStation

Overview

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.

Miva Configuration

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.

XML Configuration File

This configuration file creates the following in Miva:

1. Creates Order Workflow Queues which Shipstation will use
   1. Shipstation_orders – This is the queue which orders ready to download will be put into
   2. Shipstation_archive – This is the queue which already downloaded orders will be put into
2. Creates Order Workflow to determine when an order is put into the queue. This can be customized to fit your unique business rules
3. Creates the Order Workflow to process the Order Acknowledgement
4. Sets up Order Custom Fields used by Shipstation
5. Sets up Product Custom Fields used by Shipstation
6. Installs the Product Image Custom Fields module to the store – This is used to include the product image when order items are pulled into Shipstation.

Create Miva API Token

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

Module:orderworkflow:OrderList_Acknowledge
Module:orderworkflow:QueueOrderList_Load_Query
OrderCustomFields_Update
OrderItemList_CreateShipment
OrderList_Load_Query
OrderShipmentList_Update
ProductList_Load_Query
Store_Load

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.

Connect ShipStation

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

Miva Connection Form

JSON API Access Token – This is copied from your Miva Admin when you created an API token earlier in the setup process.

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 Types

Order 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:

Syncing Orders to ShipStation

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:

• There is at least 1 payment record
• The order is not currently Shipped, or in a Returned State

Manually Move an Order Into the ShipStation Queue

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.

Order Import Logic & Mappings

Order Status Mappings

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

Product Identifier Logic

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.

Updates to Orders After Initial Sync

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.

Example:

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 and Notes Mappings

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.

Sync Pagination

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.

Product Fields

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.

https://connect.shipengine.com/docs/reference/product-identifiers

Pushing Tracking Numbers to 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)

Splitting Shipments

ShipStation allows you to split an order into multiple shipments. There are two type of split shipments

1. Moving an entire line item to its own shipment – This is fully supported and will create a new shipment in Miva.
2. Splitting a line item (quantity) into multiple line items – While Shipstation will let you do this, there is a limitation where once either of the line items are shipped in ShipStation, the entire original line item is marked as shipped in Miva.

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.

Combining Shipments

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.

Kit Behavior

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

Order Acknowledgements

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:

1. Add a Note to the Order
2. Move the Order into the Shipstation Archive Queue

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.

Migration Guide

For existing customers using the older module based integration, below are the steps to take to setup the new integration and remove the old version.

1. Make note of the last order imported into ShipStation then go into Settings > Domain Settings > Modules tab, locate the Shipstation module and uncheck the Active box to Deactivate the old ShipStation module.
2. Follow the same setup instructions outlined in this document to setup the new connection between Miva and Shipstation. This will setup a completely separate connection.
3. Once the connection is successfully working, manually add any missing orders into the ShipStation queue starting from the order number in the first step.
4. Once you have had the new connection successfully setup for a few weeks, it's recommended you go back in and completely uninstall the old Shipstation module.
5. Since this will setup a new connection to ShipStation any historical data/orders will live under the older connection in ShipStation. If you need help migrating this data over to the new connection, contact ShipStation Support. Note: There will be an automatic migration path for this data at some point in the future.