WooCommerce

The WooCommerce integration connects a WordPress/WooCommerce web shop to Boxture. Paid orders flow into Boxture as sales orders, products are imported from the shop, stock levels in the shop follow Boxture's inventory, and when an order ships the shop order is completed with its tracking information.

What is synchronised

Data	Direction	When
Orders	WooCommerce → Boxture	Immediately, through the order webhooks
Order changes (contacts, lines)	WooCommerce → Boxture	Through the "order updated" webhook
Products and categories	WooCommerce → Boxture	Through the product webhooks, and a scheduled import at :00 and :50 past every hour
Stock levels	Boxture → WooCommerce	Every 30 minutes for changed products, and a full update every night at 02:00
Order status and tracking	Boxture → WooCommerce	A few seconds after a shipment is shipped

Before you start

You need:

• the address of the shop, for example https://shop.example.com;
• a REST API key created in WooCommerce (WooCommerce › Settings › Advanced › REST API) with read/write permissions: a consumer key and a consumer secret;
• a Boxture user for the integration, with access to the account and location that will fulfil the orders;
• the WooCommerce Shipment Tracking extension, if tracking numbers should appear in the shop.

Setting up the integration

1. Go to Admin › Integration › Third party and choose Woocommerce in the create menu.

2. Fill in the Basic tab:

   Field	What to enter
   Name	A name to recognise the shop by.
   Endpoint	The shop's address.
   Consumer key, Consumer secret	The WooCommerce REST API key.
   User	The Boxture user the integration works as. Orders are created for this user's account.
   Metadata	Optional YAML settings, see below.

3. Save. The Webhooks tab now appears.

4. On the Webhooks tab, switch on the webhooks you need. Boxture registers each webhook in WooCommerce for you.

Metadata options

Key	Meaning	Default
origin_location	The Boxture location (ID or name) set as origin location on the order lines
product_weight_unit	The weight unit used in the shop	kg
product_dimensions_unit	The dimensions unit used in the shop	cm
product_currency	The currency of the shop's prices

origin_location: Amsterdam DC
product_weight_unit: kg
product_dimensions_unit: cm
product_currency: EUR

Webhooks

Webhook	Effect in Boxture
Order created	Creates the order
Order updated	Updates the order if it already exists and is not cancelled; otherwise creates it
Product created, Product updated, Product restored	Creates or updates the product
Product deleted	Expires the product in Boxture

Switching a webhook off disables it in WooCommerce; switching it on again re-activates it.

TIP

Switch on at least Order created and Order updated. Boxture does not fetch orders on a schedule, so without these webhooks no orders come in.

Orders

Which orders are imported

Only orders with the WooCommerce status processing and a payment date are imported; in WooCommerce "processing" means the order has been paid. Orders that are pending payment, on hold or failed are ignored until they become processing (the "order updated" webhook then brings them in). An order that was already imported is not imported again.

How fields are mapped

Boxture	Taken from WooCommerce
Order type and channel	Sales order on the channel "WooCommerce"
Customer reference number	The WooCommerce order ID
Notes	The customer's note
Customer	Found or created by the WooCommerce customer's username
Delivery contact	The shipping address
Billing contact	The billing address
Order lines	Product, quantity, price and tax per line

Products are matched in this order: by SKU, by the WooCommerce product ID Boxture has linked before, and by product name. Each is compared with the Boxture product number or a product alias on the "WooCommerce" channel.

Shipping method. The WooCommerce shipping method is not taken over. The order gets the default shipping method (see Shipping › Default shipping method), which you can set per channel; choose the channel "WooCommerce" to give shop orders their own default.

WARNING

Order lines whose product cannot be found are left out; the order is created with the remaining lines. If none of the lines can be matched, the order is not created at all. Make sure every SKU in the shop exists in Boxture as a product number or a WooCommerce alias.

Valid and invalid orders

A valid order is confirmed straight away and continues like any other sales order (see Sales orders). An order with invalid details, for example a missing address field, is created and put on hold with the reason "invalid order details". Correct it and release the hold. See Holds.

Order changes

When an order changes in WooCommerce, Boxture updates the delivery and billing contacts as long as they can still be edited, and adds or changes order lines as long as the lines can still be edited (allocation is undone and redone as needed). If none of the lines match a Boxture product any more, the order is cancelled.

Cancelling an order in WooCommerce does not cancel it in Boxture by itself. Cancel it in Boxture as well, if it has not shipped. See Cancelling.

Products

Products are imported from published WooCommerce products and their variations:

• the product number is the SKU in capitals (or the name if there is no SKU);
• name, description, first category, weight and dimensions (1 when empty), price (as cost price) and images are copied;
• the EAN is read from the product's _alg_ean field, as used by common EAN plugins;
• a product is serialized unless its _is_serial_number field is "no";
• a product is expirable when it has an _expiration-date field.

A product whose number already exists in Boxture is not imported again. Products deleted in WooCommerce are expired in Boxture.

Stock levels

Every 30 minutes Boxture sends the stock quantity of each product whose inventory changed: it switches on "manage stock" for the WooCommerce product and sets the stock quantity to the available inventory over all of the account's locations. Every night at 02:00 it updates all products and variations. A Boxture product is matched to the WooCommerce product whose SKU or name equals the Boxture product number.

The inventory reporting percentage is not applied to WooCommerce; the shop always receives the full available quantity.

Shipping feedback

A few seconds after a shipment for a WooCommerce order is shipped, Boxture updates the shop order:

• the status becomes completed when everything has shipped, or stays processing when part of the order is still to come;
• the carrier, tracking link, tracking number and products of each parcel are added as shipment tracking items, which the Shipment Tracking extension shows to the customer.

Monitoring and troubleshooting

• The Third party list shows Last order at and the Connection status traffic light. See Connection status.
• Failed background jobs (an order that could not be created, a stock update that failed) are listed under Exceptions.

Problem	Check
No orders come in	Are the order webhooks switched on and active in WooCommerce? Is the order status "processing"?
An order is missing lines	Do the SKUs exist in Boxture as product number or WooCommerce alias?
Stock is not updated	Does the WooCommerce product's SKU or name equal the Boxture product number? Are the API keys read/write?
No tracking in the shop	Is the Shipment Tracking extension installed?