Table of Contents

WooCommerce

Colin Updated by Colin

WooCommerce

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

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.

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
  1. Download the file named woocommerce-shipstream-sync.zip from the Releases page
  2. Visit your WooCommerce dashboard
  3. On the left side, click Plugins
  4. Click Add New Plugin
  5. Click Upload Plugin
  6. Click Choose File and select the file you downloaded in step 1
  7. Click Install Now
  8. Click Activate Plugin
The steps may be repeated to update the plugin.

Configuration

You can update the extension configuration by navigating to the ShipStream Sync tab in the WooCommerce Settings.

Read about the Order Fulfillment Workflow to better understand how you should configure the extension for your specific needs.

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 if you still prefer to handle it manually.

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. Designing a workflow that simply updates the order status to Ready to Ship based on your specific needs is all that is required to 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.

  1. Navigate to System > Integrations > Merchant Integrations
  2. Click Add New Subscription
  3. Select the appropriate Merchant
  4. Select the WooCommerce plugin
  5. Enter the WooCommerce Store URL (e.g. https://my-woo-shop.com)
  6. Set the other configuration as needed (you can also do this later):
    1. 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.
    2. 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.
    3. 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 to be imported.
  7. Click Save Subscription
  8. 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.

  1. Click Approve and you will be redirected back to the ShipStream page where you can see your Connection Status.
If the URL of your ShipStream instance changes you will need to Deactivate and then Activate again to update the callback URL which is saved in the WooCommerce store's state data.

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.

For 3PLs the word ShipStream will be replaced with your company name.

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 as Y-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.')
}

How did we do?

Webhooks

UPS

Contact