ShipStation supports three kinds of integration:
- Custom store integration
- Connect ShipStation as a Store
- Connect ShipStation as a Shipping Service
Both kinds are supported by DEAR, but serve different purposes.
- Custom store takes orders from DEAR, sends them to ShipStation to be fulfilled, then sends back a tracking number for the DEAR order.
- ShipStation Store downloads order data from the ShipStation storefront to be synced with DEAR stock levels.
Connecting ShipStation as a Shipping Service currently is only used to estimate Shipping Rates. In the future, this will be expanded to offer the whole fulfillment service, replacing the Custom Store integration.
This document will only focus on the API Integration ShipStation for e-Commerce.
- Familiarity with the Processing a Sale process (necessary)
- Familiarity with Products and Product Management (necessary)
- ShipStation Store Integration
- Orders and Sales
- Operation Logs
ShipStation Integration Setup
Custom Store and Shipping Service are mutually exclusive and cannot be connected at the same time. If you attempt to connect both, you will receive a message in DEAR asking if you wish to change the integration type. Custom Store or Shipping Service can be connected at the same time as the e-commerce API, however, only one ShipStation account of each type can be connected at any one time.
NOTE: If user using both types of integration (Custom Store and API) there are some validations to prevent user data being damaged:
Unable to download data from ShipStation (API) if this data was first exported from DEAR using(Custom store Integration). Data will not saved.
Unable to export (Custom Store Integration) sale orders, which were downloaded fromShipStation (API).
First you must connect DEAR to ShipStation.
To connect ShipStation to DEAR:
- Navigate to Integration -> Shipstation
- Click the + to connect a new store.
- Enter your API credentials and click Connect ShipStation as a Store. You can find your API credentials in the API settings of your ShipStation account.
In the Setup tab, several integration settings can be customised.
This option specifies when a ShipStation Order will be captured: when it is created, when it is paid, when it is no longer on hold or when it is shipped. This setting is also taken into account when downloads of historical orders from ShipStation are triggered.
DEAR - ShipStation Integration allows two options for order consolidation.
No Consolidation indicates that sales will be captured from ShipStation once an hour as individual sales. Daily Consolidation will consolidate all orders from that day into a single order. When Daily Consolidation is chosen, an additional setting becomes available: Consolidation Time. This is your local time when all pending orders aggregated during the day will be processed.
See Pending Order Processing section for more details below.
For the pending order processing to be successful, an existing customer must be selected.
When Consolidation Type is Daily Consolidation, this customer is used to create a new sale task which will combine all daily sales. A customer can be created in DEAR just for this purpose.
Choose which DEAR price tier to use when DEAR downloads products from ShipStation or updates product information.
Pick, Pack and Ship Processing Mode
When pending orders are processed by DEAR new sale tasks are created. This setting tells DEAR if it should try to Auto Pick, Auto Pack and Auto Ship these tasks. If there is not enough stock on hand to pick the full quantity of products in an order, then pick will remain in Draft state and Pack and Ship won’t be completed.
DEAR does not pick up shipment information from ShipStation if auto-ship is selected and will not create fulfilment in ShipStation in this scenario (if Auto Ship is enabled).
You can control Invoice Status for Sale tasks created as a result of pending order processing. By default, Invoice will not be authorised and will be in Draft state, adjustable and waiting for authorisation. However if this setting is changed to AUTHORISED the invoice will be automatically authorised and pending sync will be created for it to sync with accounting application of your choice.
Optional revenue account
Revenue account to be used for all sales downloaded from ShipStation. This will override settings at the Product/Customer level and any other Account mapping.
Shipstation Dimension Units
To avoid discrepancy, this setting must match the dimension setting from your ShipStation account. You can find your ShipStation dimension settings by going to ShipStation -> Account Settings -> Display Options -> Time and Units.
Sales Representative Name
This option allows the shop name to be used as Sales Representative.
Option to choose automatic mapping by SKU or manual mapping by the user. The existing product will be searched for automatically by SKU, and if a product is found with a matching SKU, then the mapping is done automatically. In the case of a completely manual mapping, the user will have to choose the appropriate DEAR product SKU the Sale Channel product relates to. Please note that automatic mapping does not exclude the possibility of changing the mapping manually later.
Create new product if not found by SKU
This option is only available when Match product by SKU is enabled. With this option enabled, if there is a product (SKU) in the Sale channel that does not yet exist in DEAR, then this product can be automatically built in DEAR based on the data received about the product from a Sale channel. The possibility of a manual build is still always available through the DEAR UI.
Use ShipStation as Master Source for DEAR Products
If this option is enabled, if a product has been changed or updated in ShipStation, the linked product in DEAR will be changed to match upon catalog download. Product changes in DEAR can include changed price, name, weight, length, pictures, and other data (except SKU) based on the product data downloaded from ShipStation. Be aware! Turning on this feature can damage your product data in DEAR.
Shipment is taxable
In Shipstation Tax is entered just as a single amount. In DEAR tax is attributed per line item, so if we enable “Shipment is Taxable” option it is distributed based on a prorated basis of total invoice lines.
If No is selected, additional charges column won't have tax attributed to it.
If Yes is selected, additional charges column will have a tax amount attributed to it on a prorated basis taken from total tax line amount.
Shipstation supports multiple locations. Map ShipStations to your DEAR Locations here.
Tax Rule Mapping
For businesses located in the United States, it is necessary to Add US place of business by clicking the button and inputting correct US address by entering correct ZIP code at first. After that, new Tax rules will be created. Generally this will be three tax rules: State, State,County and State,County,City. These tax rules will be automatically applied to sale invoice lines (products) downloaded from ShipStation and having Shipping Address in US.
When pending order is processed by DEAR, a sale task is created. Each order and invoice line is assigned a tax rule. The tax rules specified in these settings will be used to create these lines.
DEAR does not apply the tax rule to recalculate tax and is simply using the actual tax amount from the ShipStation order. This means that if certain products are not Taxable or with varying tax in ShipStation, all data and totals in DEAR will look identical to ShipStation, but with DEAR tax rule name selected in this setting.
In case of tax recalculation Tax amount will be overwritten with value calculated by DEAR Taxation rule.
IMPORTANT: Orders will be skipped on download if Taxation mapping not finished!
Payment Account Mapping
DEAR can capture payments made against orders in ShipStation and is able to automatically add payments to a created sale invoice. To do this, Payment Account Mapping must be completed on this integration settings screen. You must choose an account which is able to receive payments from the chart of accounts.
This setting is not mandatory - if payment mapping is not completed, orders are still captured and downloaded from ShipStation, but payments must be manually added to invoices in DEAR. Some customers prefer to keep invoices open and then reconcile them with payouts from ShipStation.
Disconnect from ShipStation store
When you disconnect from ShipStation store, DEAR removes all associations between DEAR objects and ShipStation, including Log and Product Catalog.
The DEAR ShipStation Catalog page allows user to Download products from ShipStation, break the link between a DEAR product and its ShipStation listing and update quantities in ShipStation according to DEAR available stock.
Products can be loaded from ShipStation to DEAR in the Catalog tab by clicking Load Products. This operation may take some time.
All products in ShipStation are mapped as simple products in DEAR. ShipStation does not support product variations and does not supply quantities, which are required in DEAR. If customer has bought a product variation in their ShipStation order, information about the selected options will be provided in Order and Invoice sections of Sale Order for each line in comment field.
When product is created/updated in DEAR during download process, there is a link established between product and variant unique ShipStation product ID and DEAR unique product ID. This link isused when products are matched against sale order lines in ShipStation and when subsequent product downloads occur.
The Category field is not mandatory for ShipStation but is a required field for DEAR. If a product has no category specified DEAR will give it product category Other.
When downloading products, DEAR tries to match existing products first to avoid creating duplicates. In ShipStation product Name (Title) could be non-unique whereas in DEAR enforces mandatory SKUs.To resolve this we are using additional option at setup tab. (see “Processing products with identicalnames” above)
During product download DEAR automatically creates product categories for all product types in ShipStation if it specified.
Normally this function is not used except for test purposes because DEAR automatically creates products when processing sale orders, and because there is no Quantity information for product in ShipStation.
Data mapping for products between DEAR and ShipStation:
|Category||Category (if specified) or Other|
|Weight||WeightOz (Converted to KG on download)|
|Product Tags||Product Tags associated with ShipStation Product|
|Product Type||Always Stock|
|Default is Price Tier 1 ||Price|
|ESCCustomField1||Product FulfillmentSKU |
Linking Catalog Products
There are three possible statuses for products in the Catalog: Not Listed or Listed.
You can download products from ShipStation and perform automatic product mapping. Products in DEAR cannot be listed in ShipStation.
There are three linking options:
Leave blank (do not tie to a product in DEAR)
Link to an existing product
Create a new product in DEAR (available if the product with the required SKU does not exist).
Orders and Sales
Processing Pending Orders
If No Consolidation is selected, each ShipStation sale is converted into an identical sale in DEAR, keeping the same customer and shipping information. These orders will be captured once an hour. If Daily Consolidation is selected, the single daily sale task will use the customer selected in the integration settings, and customer, billing and shipping information imported from ShipStation will be ignored.
When processing orders, the logic is identical to that of the DEAR UI. DropShipping, Kitting and other important scenarios are implemented in the same was as through the DEAR UI.
Pending Orders can be processed manually by clicking Process. They can then be viewed in the Log tab.
Cancelling an order in ShipStation will NOT cancel or void the linked sale task in DEAR. The sale must be manually voided in DEAR.
The Load Customers button can be found next to Load Products.
This function downloads all customers from ShipStation to DEAR. If the customer already exists in DEAR, this function updates any details that have been changed in ShipStation. As DEAR automatically creates customers when processing sale orders (if No Consolidation option is selected), this function is generally only used for testing purposes.
This function creates a customer in DEAR with Contact, Billing and Business addresses captured from ShipStation.
Downloading Orders and Payments
Orders are automatically downloaded every hour if they have been created or changed in ShipStation.
NOTE: Generally, you do not need to trigger manual order download, however if an order was not captured by DEAR or to load historical sales you can use manual Load Order option.
Any imported order is saved to the Pending Orders section. It is a temporary storage of all sales and payments in DEAR. If an order already has an entry in the Log (i.e. was imported previously) it will be skipped. This guarantees that no duplicate sales will be created by DEAR.
While saving orders, DEAR captures customer information, billing and shipping addresses. All line items are captured together with quantities, prices and totals. Total order discounts are applied as are additional charges to the whole order, without distribution by lines to reduce the chance of discrepancy.
Invoice Adjustment lines are also saved as additional charges in Sale invoice named Shipping.
If a Payment Account has been specified in the Integration Settings, DEAR will always assign associated payments to the captured ShipStation orders.
For each line in Sale Order DEAR tries to locate corresponding product by SKU. If no product found, DEAR tries to download product info from ShipStation with the same logic as in Download Products function. If product info is not found DEAR marks this line as Service (Non-product). Next the Sale line is saved to pending orders with all data from ShipStation: Tax, quantity and Total.
The final step in the order download is to trigger update of stock levels in other ShipStation stores and other connected eCommerce channels.
Cancelling an order in ShipStation will NOT cancel or void the linked sale task in DEAR. The sale must be manually voided in DEAR.
Updating Fulfilment in ShipStation
When Shipment is authorised in DEAR and the carrier specified, DEAR will try to create order shipment information in ShipStation. This will only work in No Consolidation processing mode.
Each captured ShipStation order once saved to Pending Orders creates a Log entry to track the link between the Sale in DEAR and in ShipStation. This eliminates the possibility of creating duplicated orders when capturing the same order several times during manual order load.
Each Log entry has a link to the sale task in DEAR. Depending on the settings selected by the user in the Setup tab, this sales task could be draft or authorised, one or more of the Pick, Pack and Ship tabs could be authorised, and payment could have been applied to the invoice.
Log entries allow you to see which Sale task reflects a particular ShipStation sale. You also have the option to delete a Log entry manually. This will allow to reprocess an order if required. Deleting a log entry will not void or delete its associated sale task.
Reloading Orders from ShipStation
If for any reason you need to reload an order from ShipStation, this can be managed from DEAR.
To reload an order from ShipStation:
- Void the sale task. A record of this will be kept in DEAR for reconciliation purposes but the transactional data will be deleted.
- Return to the ShipStation integration Log tab and delete the Log entry. This will allow the order to be recaptured from ShipStation.
- Navigate to the Pending Orders tab and click Load Orders, making sure the date is set to before when the order to reload was made.
Each time when user or DEAR downloading sales appropriate record added to operation log. It also contains information about results of downloading, including the count of processed, skipped or cancelled orders.