WooCommerce support both webhooks (Documentation) and REST API (Documentation) integration methods. These can either be in-built (Settings ->Advanced -> REST API or Webhooks) or using a third party plugin. The REST API will allow you to receive order completion statusses from Blue Sage (Order -> Completed or Order -> Failed), or if you are using WooCommerce Order Status Manager (by SkyVerge), the custom order status required. REST API integration is interactive. Webhooks on the other hand push notifications and data. As with Wix and Shopify, a large amount of data is pushed which is not required for the tasking process. As a result, we recommend looking into third-party webhook plugins (some free and some commercial) (Plugins Tagged as Webhook Providers) and integration capabilities instead, as this allow you to only send throught the data elements required for the tasking process. We suggest you investigate WunderAutomation by Wundermatics, as it allows for all of your basic needs. Please note we are not affiliated to these institutions.
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "BlueSageCouriersWooCommerceReceiver",
"description": "Blue Sage Couriers WooCommerce Receiver Webhook Schema",
"type": "object",
"properties": {
"senderID": {
"description": "Blue Sage Couriers Merchant Identifier",
"type": "string",
"$comment": "Obtain the Merchant Code by Registering with Blue Sage Couriers - Required"
},
"orderID": {
"description": "Order Identifier",
"type": "integer",
"$comment": "Retrieve via {{ order.id }} - Required"
},
"status": {
"description": "Order Status",
"type": "string",
"$comment": "Retrieve via {{ order.status }} - Optional see notes about Customer Order Statusses"
},
"number": {
"description": "Order Number",
"type": "string",
"$comment": "Retrieve via {{ order.number }} - Optional requires Sequential Order Number Plugin"
},
"customerEmail": {
"description": "Order Email",
"type": "string",
"$comment": "Retrieve via {{ order.email }} - Required"
},
"customerNote": {
"description": "Order Notes",
"type": "string",
"$comment": "Retrieve via {{ order.customer_note }} - Optional only relevant if notes include access instructions"
},
"billing_firstName": {
"description": "Billing Details - Firstname",
"type": "string",
"$comment": "Retrieve via {{ order.billing_first_name }}} - Required"
},
"billing_lastName": {
"description": "Billing Lastname",
"type": "string",
"$comment": "Retrieve the Order Notes via {{ order.billing_last_name }} - Required"
},
"billing_company": {
"description": "Billing Company",
"type": "string",
"$comment": "Retrieve via {{ order.billing_company }} - Optional"
},
"billing_email": {
"description": "Billing eMail",
"type": "string",
"$comment": "Retrieve via {{ order.billing_email }} - Required"
},
"billing_phone": {
"description": "Billing Phone",
"type": "string",
"$comment": "Retrieve via {{ order.billing_phone }} - Required - should be mobile cell phone number"
},
"billing_address1": {
"description": "Billing Address Line 1",
"type": "string",
"$comment": "Retrieve via {{ order.billing_address_1 }} - Required"
},
"billing_address2": {
"description": "Billing Address Line 2",
"type": "string",
"$comment": "Retrieve via {{ order.billing_address_2 }} - Required"
},
"billing_city": {
"description": "Billing City",
"type": "string",
"$comment": "Retrieve via {{ order.billing_city }} - Required"
},
"billing_state": {
"description": "Billing State or Province",
"type": "string",
"$comment": "Retrieve via {{ order.billing_state }} - Required"
},
"billing_country": {
"description": "Billing Country",
"type": "string",
"$comment": "Retrieve via {{ order.billing_country }} - Optional"
},
"billing_postcode": {
"description": "Billing Postal Code",
"type": "string",
"$comment": "Retrieve via {{ order.billing_postcode }} - Required for address completeness"
},
"shipping_firstName": {
"description": "Shipping Firstname",
"type": "string",
"$comment": "Retrieve via {{ order.shipping_first_name }} - Optional - see discussion on shipping address details and order of validation"
},
"shipping_lastName": {
"description": "Shipping Lastname or Surname",
"type": "string",
"$comment": "Retrieve via {{ order.shipping_lastName }} - Optional - see discussion on shipping address details and order of validation"
},
"shipping_phone": {
"description": "Shipping Phone",
"type": "string",
"$comment": "Retrieve via {{ order.shipping_phone }} - Optional - see discussion on shipping address details and order of validation"
},
"shipping_company": {
"description": "Shipping Company",
"type": "string",
"$comment": "Retrieve via {{ order.shipping_company }} - Optional - see discussion on shipping address details and order of validation"
},
"shipping_address1": {
"description": "Shipping Address Line 1",
"type": "string",
"$comment": "Retrieve via {{ order.shipping_address1 }} - Optional - see discussion on shipping address details and order of validation"
},
"shipping_address2": {
"description": "Shipping Address Line 2",
"type": "string",
"$comment": "Retrieve via {{ order.shipping_address2 }} - Optional - see discussion on shipping address details and order of validation"
},
"shipping_city": {
"description": "Shipping City",
"type": "string",
"$comment": "Retrieve via {{ order.shipping_city }} - Optional - see discussion on shipping address details and order of validation"
},
"shipping_state": {
"description": "Shipping State or Province",
"type": "string",
"$comment": "Retrieve via {{ order.shipping_state }} - Optional - see discussion on shipping address details and order of validation"
},
"shipping_country": {
"description": "Shipping Country",
"type": "string",
"$comment": "Retrieve via {{ order.shipping_country }} - Optional - see discussion on shipping address details and order of validation"
},
"shipping_postcode": {
"description": "Shipping Postal Code",
"type": "string",
"$comment": "Retrieve via {{ order.shipping_postcode }} - Optional - see discussion on shipping address details and order of validation"
},
"dispatchReadyDate": {
"description": "Dispatch Ready Date",
"type": "string",
"$comment": "Retrieve via {{ order.acf | key: 'field_xxxx' }} - Optional - see discussion on using Advanced Custom Fields (ACF) to add dates to orders"
},
"dispatchReadyDateMask": {
"description": "Shipping Firstname",
"type": "string",
"$comment": "Enter Date Mask (example YYYYMMDD) - Optional - see discussion on using Advanced Custom Fields (ACF) to add dates to orders"
},
"taskAction": {
"description": "Task Action",
"type": "string",
"$comment": "Required Enter either UPDATE or CANCELLED"
}
},
"required": [
"senderID",
"orderID",
"customerEmail",
"billing_firstName",
"billing_lastName",
"billing_email",
"billing_phone",
"billing_address1",
"billing_address2",
"billing_city",
"billing_state",
"billing_postcode",
"taskAction"
]
}Order Status
If you want to implement custom order statusses, then the ORDER STATUS slug can be used to apply additional validation to the in-bound validation process (receiving the task and checking that the status is a valid pre-agreed status), and the out-bound (updating the order status in your store). You can therefore create intermediate statusses in the store that will allow you to monitor the delivery status of the order. For example:
- DISPATCH READY – wc-order-ready status – will allow us to add the task to our daily work schedule
- DISPATCHED – wc-order-dispatched status – inform you that the order is out for delivery
- DISPATCH COMPLETED – wc-order-completed status – inform you that the order was delivered.
It should be noted that the in-built WooCommerce Analytics only update when the order status change to COMPLETED, and as a result, you would need to manually close orders.
Shipping Address Details
Not all WooCommerce store owners make the Shipping Address mandatory or required. As a result, our validation process will substitude Billing Address Details for Shipping (Delivery Address) details if we detect that these details are missing.
Dispatch Ready Date
In order to implement a Dispatch Ready Date (when the order is ready for Blue Sage Couriers to collect and deliver), you would need to either use the Advanced Custom Fields (ACF) Plugin from WP Engine (there are many others that can be selected) or the PODS Plugin from the Pods Foundation to extend the current WooCommerce order schema to include a date. This date must be set by the shop manager or shop owner. You can also use this date to notify customers about collections ready, for example. Please note Blue Sage Couriers are not affiliated with these institutions or organisations.
The second field required, when presenting the dispatchReadyDate field, is the dispatchReadyDateMask field. This is necessary as different systems interpret dates differently. If the field is to be present, we require the text value of dispatchReadyDate field, and the associated date mask dispatchReadyDateMask to be able to parse the text field into a date.
Receiving Feedback
You have three options or methods whereby you can receive feedback on the progress of the task or delivery:
- Either via eMail – will be configured in your mechant profile and use the notifications email for this purpose.
- Either real time via the REST API – require a read/write REST API Key for WooCommerce. We will provide details on planning and delivery as private order notes, and transaction completion by changing the order status to COMPLETED or your custom order status.
- Either semi-realtime via Webhooks. This require some coding in your WooCommerce, as we can post back to your store to a predefined webhook receiver. A typical response JSON Schema defined below.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "BlueSageCouriersResponder",
"description": "Blue Sage Couriers Webhook Response Schema",
"type": "object",
"properties": {
"senderID": {
"description": "Blue Sage Couriers Identifier",
"type": "string",
"$comment": "BLUESAGE"
},
"orderID": {
"description": "Your Internal Order Identifier",
"type": "integer",
"$comment": "Your Internal Order ID"
},
"orderStatus": {
"description": "Your Order Status",
"type": "string",
"$comment": "Order Statusses in Text (Example COMPLETED, PLANNED, FAILED)"
}
},
"required": [
"senderID",
"orderID",
"orderStatus"
]
}Internal Order Statusses
You can read about the internal work order statusses and processes in the associated article. A key differentiator for Blue Sage Couriers, is our centralized route optimisation, planning and notification services, all included in your your delivery fee. You can gain some insights into this feature and function in this article.
