Docs
This integration completely replaces the legacy ShipStation Export Tool for new customers since 8th Nov 2018. If you were using the export tool, you can still access it under Settings > Import & Export Data > Export for ShipStation. To avoid duplication of orders in ShipStation, it is advised not to use the tool along with this integration.
ShipStation is a web-based shipping and fulfillment software. Amongst a host of features, ShipStation helps you:
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.
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 |
List of fields mapped between ShipStation and Chargebee.
When the sync runs, whether manual or auto sync, the following steps take place:
Let's discuss the above steps in detail:
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.
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:
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.
Let's look at how the sync rules are configured and how the sync runs for the first time.
1. Connect your ShipStation Account
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
You may want to have an Inventory SKU field for every item in your Chargebee Product Catalog which you wish to map to ShipStation. To do this, create a custom field at the plan and addon level with the API name as cf_inv_sku. This field would then be 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.
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
2. Sync All Orders
Once on the final page of the integration after you have completed the initial setup and sync, you can modify your settings:
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.
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. |
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. |
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.
Articles & FAQ