Table of Contents
WooCommerce
Updated by Colin
ShipStream's WooCommerce integration is a direct integration with WooCommerce shopping carts which provides the following functionality:
- Keep available inventory synchronized from ShipStream to WooCommerce
- Import Orders from WooCommerce to ShipStream
- Send tracking tracking information for packed/shipped orders to WooCommerce
This integration uses two-way communication so that updates occur immediately and efficiently rather than relying on slow or inefficient polling mechanisms. It eliminates potential for race conditions with a basic locking mechanism for order submission and performs accurate inventory level adjustments using a single transaction within WooCommerce's database.
Requirements
The WooCommerce integration can connect to a WooCommerce store which meets the following requirements:
- Wordpress 6.3+
- WooCommerce 8.7+
- Install the ShipStream WooCommerce Sync extension
Tracking Extensions
It is recommended to install a Shipment Tracking extension. If a supported one is not detected, the tracking information will be added as an order note visible to the customer.
- WooCommerce Shipment Tracking
- Unimplemented extensions - contact us for support:
ShipStream WooCommerce Sync Extension
The ShipStream WooCommerce Sync Extension is a companion to the ShipStream integration and does the following:
- Adds three new Order Statuses to facilitate straightforward and transparent order synchronization.
- Adds a bulk action for "Change to Ready to Ship".
- Exposes additional API endpoints and actions to facilitate a two-way communication and efficient operation.
Installation
- Download the file named
woocommerce-shipstream-sync.zip
from the Releases page - Visit your WooCommerce dashboard
- On the left side, click Plugins
- Click Add New Plugin
- Click Upload Plugin
- Click Choose File and select the file you downloaded in step 1
- Click Install Now
- Click Activate Plugin
Configuration
You can update the extension configuration by navigating to the ShipStream Sync tab in the WooCommerce Settings.
Order Fulfillment Workflow
It is important to understand how the integration workflow fits into WooCommerce. It is done primarily through order statuses.
- Changing the WooCommerce order status to Ready to Ship triggers the plugin to notify the ShipStream integration that a new order is ready to be imported.
- Within seconds, ShipStream will try to import the order. If successful, the WooCommerce order status is updated to Submitted, otherwise it is updated to Failed to Submit.
- If the order import fails and the order status is changed to Failed to Submit, nothing further will happen until the order status is changed again to Ready to Ship. This is a manual process that should be done when the issue has been resolved and you'd like to attempt the import again.
There are multiple ways you can trigger the transition from Processing to Ready to Ship, including but not limited to:
Manually Update Order Status
Just change the order status to Ready to Ship for any order that you want to be picked up by ShipStream. This is good for testing so you can verify each step as it happens but doesn't scale well for large stores. However, we have added a Change to Ready to Ship bulk action on the WooCommerce Orders grid to make this easier.
Auto-Fulfill Option
The Auto-Fulfill Orders option is enabled by default and will cause the order status to advance from Processing to Ready to Ship automatically. This will apply to all orders that have one or more physical items so is good for simple scenarios where you want every order fulfilled from the same source. For more control, there are other options.
AutomateWoo Plugin
You can disable Auto-Fulfill Orders option and use the AutomateWoo plugin with a configuration customized to your needs. Here is an example:
- Trigger: Order Status Changes to Processing
- Rule: Order total is less than $300
- Action: Change Order Status to Ready to Ship
So, it is not necessary for AutomateWoo to be involved in the integration communication, simply design a workflow that updates the order status to Ready to Ship based on your specific needs and let the extension handle the rest.
Custom Code
The ShipStream Sync extension provides a simple action that your custom code can call to update the order status to Ready to Ship and trigger the real-time update. Here is an example:
do_action('shipstream_ready_to_ship', $order, 'My code decided it is time...');
ShipStream Setup
You are now ready to create and configure a Merchant Integration Subscription in ShipStream.
- Navigate to System > Integrations > Merchant Integrations
- Click Add New Subscription
- Select the appropriate Merchant
- Select the WooCommerce plugin
- Enter the WooCommerce Store URL (e.g.
https://my-woo-shop.com
) - Set the other configuration as needed (you can also do this later):
- The WooCommerce shipping methods and descriptions must be "translated" from the WooCommerce values to the ShipStream equivalent. Add one or more Shipping Method Translation rules.
- The Order Transform Script allows you to specify more advanced modifications to the new order data before the order is created using the WooCommerce order data.
- Optionally specify a Sync Orders Since date if you would like to pull in existing orders using the Sync Orders button after the subscription is saved. The orders must still have the Ready to Ship status in order to be imported.
- Click Save Subscription
- Click the Connect WooCommerce Store button that appears after the subscription is created.
At this point, you will be asked to login to your WooCommerce store if you are not yet logged in, and then Approve or Deny the request to provide ShipStream access to your WooCommerce store.
- Click Approve and you will be redirected back to the ShipStream page where you can see your Connection Status.
User Guide
By default the orders are automatically updated to Ready to Ship status and therefore no action is required once payment is received.
The three new statuses added by the WooCommerce ShipStream Sync plugin are as follows and highlighted in blue in the diagram below:
- Ready to Ship - the order is cleared to be submitted to ShipStream
- Failed to Submit - there was an error submitting the order to ShipStream
- Submitted - the order was successfully submitted to ShipStream
Manual Updates
If you disable the Auto-Fulfill Orders option, you will need to manually change the Status to Ready to Ship by choosing the status from the dropdown and then clicking Update.
Once the order has been imported successfully, the order status will advance to Submitted with a comment indicating the ShipStream Order number.
Completing Orders
Once an order is successfully submitted to ShipStream (as indicated by the Submitted order status in WooCommerce), any time a new Shipment in ShipStream advances to Packed or Shipped status, the event data will be pushed to WooCommerce to record the tracking information. Once the ShipStream order is complete, the WooCommerce order will also automatically advance to Completed.
Therefore, one can assume that any orders that are in Submitted status in WooCommerce have been transmitted to ShipStream successfully, but have not yet been packed out and any orders that are Completed in WooCommerce have been not only submitted to ShipStream, but also picked and packed or shipped.
Cancelling Orders
There are many different scenarios where one might need to cancel an order. Canceling an order in ShipStream will change the WooCoommerce order from Submitted to On hold, but otherwise handling cancellations will need to be handled manually on both ends.
Scripting Guide
The Order Transform Script allows you to modify the order data before it is submitted to ShipStream's order creation API.
The variables that are in the context of the script execution are:
order
- The order data as it will be submitted to the order.create API method. Contains the following properties:store
items
address
options
timestamp
- Read-only instance of a PHP DateTime object for easily authoring time-based conditionals.
wooCommerceOrder
- The order data received from WooCommerce.order_id
order_number
coupon_codes
created_via
customer_id
customer_note
customer_order_notes
date_created
- Formatted asY-m-d H:i:s
payment_method
shipping_address
billing_address
shipping_method
status
subtotal
total
items
product_id
sku
name
quantity
product_type
price
shipping_class
stock_managed_by_id
tag_ids
tax_class
tax_status
category_ids
shipping_lines
Example: Copy the WooCommerce billing address phone number to the telephone number field if it wasn't already set.
if ( ! order.address.telephone && wooCommerceOrder.billing_address.phone) {
order.address.telephone = wooCommerceOrder.billing_address.phone
print('Use billing address phone number for telephone number fallback.')
}