Docs

ShipStation 

Introduction 

ShipStation is a web-based shipping and fulfillment software. Amongst a host of features, ShipStation helps you:

  • Automate fulfillment for shippable orders
  • Print labels for shipping
  • Validate shipping addresses
  • Benefit from discounted shipping rates
  • Split or merge orders
  • Manage your inventory

Chargebee's ShipStation integration automatically moves new orders created in Chargebee into ShipStation and performs a two-way sync for such orders between the platforms. So while Chargebee takes care of billing your customers, their shippable orders are easily communicated to ShipStation for fulfillment.

Note:
ShipStation is only available for customers in US, Canada, Australia and UK.


Order Status Mapping 

The table shows how order statuses in Chargebee and ShipStation are mapped to each other during syncing:

Chargebee Order Status ShipStation Order Status
Queued None
Awaiting Shipment Awaiting Shipment (for paid orders)
Awaiting Payment (for unpaid orders. Unpaid orders can happen when payment is removed from queued orders in Chargebee.)
Cancelled Cancelled
On hold On hold
Shipped Shipped
Delivered There is no counterpart for this in ShipStation
Partially Delivered There is no counterpart for this in ShipStation
Returned There is no counterpart for this in ShipStation
See also

List of fields mapped between ShipStation and Chargebee.


The Syncing Process 

When the sync runs, whether manual or auto sync, the following steps take place:

  1. Queued orders in Chargebee are moved into ShipStation.
  2. Changes made to previously synced orders are updated from Chargebee to ShipStation and vice versa.

Let's discuss the above steps in detail:

1. Moving queued orders into ShipStation 

  • Orders in Chargebee that meet the sync prerequisites are moved into ShipStation. The fields from Chargebee that are synced and their mapped fields in ShipStation are listed here.
  • Once moved, the order statuses for those orders change to Awaiting Shipment in Chargebee.
  • The Reference Id and Fulfillment status fields for the orders are immediately updated in Chargebee from ShipStation.
  • This table lists additional events that happen when an order is moved into ShipStation.

2. Syncing changes for previously moved orders 

Case 1: Changes in Chargebee

If previously synced orders have been updated in Chargebee since the last sync, any change affecting the following fields are synced to ShipStation. (Changes in other fields are not synced):

Some specific cases that are handled while syncing changes from Chargebee to ShipStation are tabulated here.

Note:
Once orders are cancelled or shipped in ShipStation, they're locked from being further updated via their API, so any updates from Chargebee for such orders do not get reflected in ShipStation.

Case 2: Changes in ShipStation

If previously synced orders have been updated in ShipStation since the last sync, any change affecting the following fields are synced back to Chargebee. (Changes in other fields are not synced):

Note:
If the Tracking Id, Shipment carrier or Batch Id are manually updated in ShipStation, they are not synced back to Chargebee.

Some specific cases that are handled while syncing changes from ShipStation to Chargebee are tabulated here.

Sync Prerequisites for New Orders 

Orders with status queued in Chargebee must meet certain conditions before they can be synced into ShipStation. Whenever the sync runs, all the orders that meet all of the following conditions are moved into ShipStation:

  • If the sync start date is set, then only those orders with order date on or after it are considered. Otherwise, all orders are considered.
  • The orders must have order status as queued.
  • The sync date of the orders should be on or before the present date.
  • The billing address and shipping address must be present for the order. This prerequisite can be relaxed to an extent in the sync rules.
  • ShipStation only supports the following currencies: GBP, USD, AUD and CAD. The integration has no way of knowing what the ShipStation native currency has been set to and so does not do any currency conversion during syncing. If you wish to have the numbers right in ShipStation, you must ensure that the currencies on both sides match. If you have multiple currencies in Chargebee, the amounts are converted to the base currency before moving to ShipStation.

Note:
If you wish to prevent an order from being synced (say, because payment has been removed for it), change its status to on hold in Chargebee.

Configuration and Initial Sync 

Let's look at how the sync rules are configured and how the sync runs for the first time.

PART A: Connecting ShipStation and Setting Sync Rules 

1. Connect your ShipStation Account

  • Navigate to Apps>Go to Marketplace> ShipStation.
  • Enter your ShipStation API Key and API Secret to authorize the integration. You can find those by navigating to Settings > Account > API Settings in ShipStation.

2. Data Validation

This step performs a check to see if the prerequisites for syncing are met. If any orders fail the check, a summary is shown and you can download a CSV file with details. This file can be used to inspect the errors better, especially for a large list.

3. Configure Sync Rules

Sync rules are settings that control the sync behavior between Chargebee and ShipStation.

You can configure the following:

  • The number of days before their shipping date that orders must be moved to ShipStation. This is called the sync date for the order.

    Example:
    If you set the number of days to 3, then when the sync runs on say, Jan 15th, eligible orders with shipping date on or before Jan 18th are moved into ShipStation.

  • In ShipStation, both the billing address and the shipping address fields are mandatory (sub-fields that are mandatory are name (either first name or last name), line 1, city, zip and country). If either one of the billing or shipping addresses is absent for the order, you can choose to have the address copied from the available field.

  • Map custom fields between Chargebee and ShipStation: all the Customer and Subscription level custom fields from Chargebee are available for mapping to ShipStation fields.

    Mapping Inventory SKU
    Optionally, you can have an Inventory SKU field for every item in your Chargebee Product Catalog which you want to map to ShipStation. To map these fields, create a custom field at the plan, addon, and charge price point level with the API name as cf_inv_sku. This field gets automatically mapped to the SKU field at the line item level in ShipStation.

4. Choose Sync Start Date
Any orders with order date preceding this date are not synced. This is useful in case you created some test orders in Chargebee which you do not want to sync. This date cannot be changed once set.

PART B: Running Initial Sync and Syncing all Orders for the First Time 

Once the configuration has been done as above, the following steps are performed to sync the very first set of orders into ShipStation.

1. Run Initial Sync

  • An initial sync is run for the first 10 orders in Chargebee.
  • Sync results follow, that show which orders were synced and which encountered errors (the errors are shown). At this point it is advisable to check ShipStation to see if the synced orders have been imported properly.
  • When errors are encountered, you may either:
    • Fix errors and retry the initial sync.
    • Leave the erroneous orders un-synced and start syncing the remaining orders (next step).

2. Sync All Orders

  1. Post the initial sync of the first 10 orders, the remaining orders can now be synced.
  2. All errors are listed and can be downloaded in a CSV file.
  3. There is an option to ignore the errors after choosing which, the affected orders are not considered for syncing again unless some change is made to them.
  4. This process leads you to the Sync Overview page (next section) which is your ShipStation integration dashboard from where you can see a summary of the last sync etc.

Sync Preferences 

Once on the final page of the integration after you have completed the initial setup and sync, you can modify your settings:

  1. Sync Now
    Run an immediate sync of orders between Chargebee and ShipStation.
  2. Auto Sync
    Auto sync, which runs the sync process every 30 minutes, can be toggled on or off. It is turned off by default.
  3. Manage sync rules
    This leads you to the sync rules page to make changes to your settings.
  4. Unlink integration
    Unlinks your ShipStation account from Chargebee so that no more order syncing happens between Chargebee and ShipStation.
  5. Last sync time and number of orders synced (on last sync) are displayed too.
  6. Sync errors
    Orders with sync errors are listed under this tab. Note that on the user interface, only up to 200 errors would be shown. You can click on download CSV to get a CSV file with all the errors. Click on Ignore all to ignore the errors and skip the erroneous orders from the next sync until they're updated.

Additional Sync Scenarios 

Apart from the cases discussed thus far on this page, there are some unique scenarios during syncing that need to be looked at more closely. We describe them below:

Splitting and Merging Orders
ShipStation allows orders to be split or merged. When an order is split, its line items become individual orders themselves. When several orders are merged, all their line items are combined to form a single order.

Chargebee to ShipStation 

This section discusses unique cases for syncing data from Chargebee to ShipStation.

Regular Orders:
This subsection is for those orders that are not split or merged in ShipStation:

Action/Event in Chargebee Impact in ShipStation
When Orders are Created
An order is created with line item discounts. Discounts can be accounted for via "negative line items" in ShipStation. So the order line items are created without discount followed by negative line items for the discounts.
Order is created with a partial payment of invoice, the remaining amount being adjusted. ShipStation does not have a counterpart for adjustment amounts. Since it only stores the total order amount and the paid amount, any adjustments need to be accounted for outside of ShipStation.

Eg. If the order amount is $50 and the paid amount is $40, both these values are stored in ShipStation. The adjustment amount then, can only be inferred as $50-$40 = $10.
Tax is applied on the orders ShipStation order amounts are tax exclusive. The tax is shown separately for every order.

Eg. If the order amount in Chargebee is $105, including 5% tax, then the order amount in ShipStation would be $100 and the tax amount would be $5.
An order is created in a currency other than the ShipStation native currency. If you have multiple currencies in Chargebee, the amount is converted to the base currency before syncing. Otherwise, no conversion happens. See last point under this section.
When Orders are Updated
Credit note (whether adjustment or refundable) is removed/voided for an order. Only paid amount for an order is accounted for in ShipStation. Since credits are not handled in ShipStation, there is no impact for such a Chargebee action in ShipStation.
Order payment is removed by removing invoice payment. The paid amount for the order in ShipStation is reduced by the removed amount and the order status (and fulfillment status field in Chargebee) is updated to awaiting payment.
Refundable credit note is raised against an order. Since the order amount and paid amount are not affected, there is no impact. There is no way to account for refunds in ShipStation.
Order is deleted. (Happens when invoice/subscription/customer is deleted.) The corresponding order in ShipStation is archived.
Order is paid/adjusted again after payment removal. If the invoice is adjusted then there is no impact. However, if a payment is recorded against the invoice, the paid amount is updated for the order.

Split and Merged Orders:

This subsection is for scenarios that involve changes in Chargebee for orders that have been split or merged in ShipStation:

Action/Event in Chargebee Impact in ShipStation
For Split Orders
Remove payment for original order. Paid amount for each split order is reduced in proportion to its share towards the order amount of the original order.
Add payment for original order. This results in Paid amount being updated in Chargebee and consequently for each split order in ShipStation.
Status update for original order. Order status is updated for all the split orders.
Delete original order. All the split orders are archived.
Refund the original order. No impact (since ShipStation does not account for refunds).
For Merged Orders
Add payment for any of the original orders. The amount is added to the paid amount of the merged order.
Remove payment for any of the original orders. Reduce the removed amount from the paid amount of the merged order.
Order status is updated for any of the original orders. No impact in ShipStation as currently the integration is unable to update order status for merged orders in ShipStation.
Delete/cancel any of the original orders. The corresponding line item(s) from the merged order is(are) deleted.
Refund any of the original orders. No impact since refunds are not accounted for in ShipStation.

ShipStation to Chargebee

This section discusses unique cases for syncing data from ShipStation to Chargebee.

Action/Event in ShipStation Impact in Chargebee
An order is cancelled Order status becomes cancelled. Credits must be raised manually in Chargebee as the credit amount is not known in ShipStation.
An order in Chargebee is split line-item-wise into individual orders in ShipStation. If the order status for any of the split orders is changed from that of the original order, the order status and fulfillment status for the corresponding line item in the original order is updated in Chargebee.

If the order status for all the split orders is changed to the same status, the order status and fulfillment status of the original order in Chargebee are updated.

If the tracking Id, batch Id or carrier code is changed for any of the split orders, then the latest change is applied to the original order in Chargebee.
A line-item (with quantity more than 1) of an order in Chargebee is split into multiple orders in ShipStation. No impact.
A split order is cancelled. Order line item status is set as cancelled.
Two or more orders are merged into one order. The fulfillment status (and thus order status), batch id, tracking id, and carrier code of all the original orders is updated based on that of the merged order.
A merged order is cancelled. All the original orders are marked cancelled. Credits must be raised manually in Chargebee as the credit amount is not known in ShipStation.

FAQ

1) How can I include shipping charges to be synced with the orders into ShipStation?
Currently, Chargebee Orders does not have direct support for shipping charges. Also, only shippable line-items in orders get synced into ShipStation. So you can create a shippable addon for your shipping charges and attach them to your subscriptions. Note that just like any shippable addon, these charges will be synced as a line-item to the order in ShipStation; they will not be mapped to shipping charges in ShipStation.

Was this article helpful?
Loading…