WooCommerce to Specter – order

Activation of the workflow for sending orders from WooCommerce to Specter is currently done with the help of Kroconnect staff.

How the sync works

The integration’s core purpose is to transfer new orders from WooCommerce to Specter through two API calls:

1. The second call uses the customer’s ID together with the order data to create the order in Specter, after which the order number is returned to WooCommerce.
2. The first call sends customer information. The email address usually serves as the unique identifier, but organization number and customer number can also be used. If the customer already exists, their ID is returned; otherwise a new customer record is created.

Preventing duplicate sends

• An order is never sent twice — if it already has a Specter order number, the plugin skips it.
• If an order was sent in the last four minutes, another send is blocked to prevent duplicates.
• Orders with the status Pending payment or Failed are not sent.

If a send fails

If a send fails (for example, a temporary network error), the plugin retries automatically in the background. There are up to 3 retries (4 attempts in total), with delays of 5 minutes, 15 minutes and 60 minutes between them. If all 4 attempts fail, the order is left unsent, and the failure is recorded in the order notes and the WooCommerce log.

Triggering an order sync

Three methods are available:

1. Via the Order sync action setting in the Kroconnect WooCommerce Connector plugin. 
   
   On payment_complete() is typically used, but other order statuses can also be selected.
2. Via a webhook in WooCommerce.
   
   The recommended event is Order paid. The webhook URL is https://api.kroconnect.com/kroconnect/{your-workflow-id}.
3. Via custom code, for specific scenarios or events.
   In some cases, there is a need to trigger order synchronization at custom times. This could involve a specific order status or a specific event that triggers the action. Below are a couple of examples of how this might look from a programming perspective.

<?php
/**
 * Trigger order sync when order is placed with WooCommerce Invoice Gateway plugin.
 * Can be useful if completed purchase status is set to On hold in plugin settings.
 */

add_action( 'woocommerce_thankyou_invoice', 'custom_send_order_to_kroconnect' );

function custom_send_order_to_kroconnect( $order_id ) {
	do_action('send_order_to_kroconnect', $order_id );
}

<?php
/**
 * Trigger order sync when order status changes to a custom status.
 */

add_action( 'woocommerce_order_status_changed', 'custom_send_order_to_kroconnect2', 10, 3 );

function custom_send_order_to_kroconnect2( $order_id, $from, $to ) {
	$order   = wc_get_order( $order_id );
	
	if( empty( $order)) {
		return;
	}
	
	if( 'my-custom-status' !== $to ) {
		return;
	}
	
	do_action('send_order_to_kroconnect', $order_id );
}

The Specter order number in WooCommerce

Specter’s order number is saved automatically in WooCommerce and shown in the order notes. To display it in a separate column:

1. Tick Specter order number column.
2. Enter your preferred column name in Specter order number title.

Sending an order manually

If an order isn’t sent automatically, it can be triggered manually via an upload icon in the Actions column of the order list. After a successful call, the order number is shown (the page must be refreshed).

How data is mapped between the systems

It is possible to customize which data is mapped from WooCommerce to Specter. By default, however, the fields are mapped as follows.

Customer

Order

Customizing the data sent to Kroconnect (developers)

The connector adds a kroconnect object to WooCommerce REST API responses, which Kroconnect reads when it fetches an order. Two filters let you add to or change that data.

kroconnect_wc_rest_order_data

Filters the kroconnect object on the order (/wc/v3/orders). By default it includes coupons_used, line_attributes and gift_cards.

• Parameters: array $data, WC_Order $order
• Returns: the modified $data array

Example — add a custom published comment to the order data:

add_filter( 'kroconnect_wc_rest_order_data', 'kroconnect_specter_published_comment', 10, 2 );
function kroconnect_specter_published_comment( $data, $order ) {
    // Add custom text to the published comment.
    $data['published_comment'] = wptexturize( get_field( 'ordertext', 'option' ) );
    return $data;
}

kroconnect_wc_rest_order_item_product_data

Filters the kroconnect object on each order line item. By default it can include display_attributes and tax_rate, plus contrl_article_id (when the Contrl integration is enabled) and customs_declaration (when the Product Fields integration is enabled).

• Parameters: array $data, WC_Order_Item_Product $order_item_product
• Returns: the modified $data array

Example — add a custom value to each order line item:

add_filter( 'kroconnect_wc_rest_order_item_product_data', 'my_add_line_item_data', 10, 2 );
function my_add_line_item_data( $data, $order_item_product ) {
    $product = $order_item_product->get_product();
    if ( $product ) {
        $data['my_custom_field'] = $product->get_meta( '_my_custom_field' );
    }
    return $data;
}