Similar to WooCommerce, Wix allow for native webhook events and send payloads to predefined receivers. Wix webhooks are triggered by real-time events relevant to your app and the sites where your app is installed. Rather than continuously polling the status of the app or site through periodic API calls, webhooks enable your app to execute code directly in response to events. For example, you can trigger an action when a site admin creates a new product or a site visitor pays for their order. You can read more about Wix Automations and Webhooks over here. Unlike WooCommerce, this requires experience, and as such, we recommend reaching out to a specialist Wix Partner such as FLOR-IT. Please note that we are not associated or affiliated with either FLOR-IT or Wix, but in our search for solutions to help you, found them! You can reach FLOR-IT via their website or email to info@flor-it.com
JSON Schema
The default webhook post include much data not required for tasking Blue Sage, as illustrated below.
[
{
"data": {
"invoices": [],
"payments": [
{
"id": "83bd9b13-dfc9-4152-93c3-517bbf960c8a",
"amount": {
"value": "0.01",
"currency": "EUR"
},
"createdDate": "2024-04-11T05:49:26.627Z",
"creditCardLastDigits": ""
}
],
"orderNumber": "10002",
"purchaseFlowId": "4c516764-8a02-4f74-a4e6-532963e4a6a5",
"cartId": "5afea49d-a786-43e2-8298-f6d7f25c7e57",
"lineItems": [
{
"quantity": 1,
"sku": "",
"totalPriceBeforeTax": {
"value": "0.01",
"currency": "EUR"
},
"taxRate": "0.0000",
"shippable": true,
"totalPrice": {
"value": "0.01",
"currency": "EUR"
},
"catalogItemId": "2ca37bf5-abbd-2d5e-0408-702a6be46ff4",
"taxAmount": {
"value": "0.00",
"currency": "EUR"
},
"totalDiscount": {
"value": "0",
"currency": "EUR"
},
"id": "00000000-0000-0000-0000-000000000001",
"itemType": "PHYSICAL",
"catalogId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
"itemName": "TEST TASING POST",
"descriptionLines": []
}
],
"paymentStatus": "PAID",
"refunds": [],
"shippingInfo": {
"price": {
"value": "0",
"currency": "EUR"
},
"taxRate": "0.0000",
"totalPriceAfterTax": {
"value": "0.00",
"currency": "EUR"
},
"logistics": {
"deliveryTime": "3-5 werkdagen",
"shippingDestination": {
"address": {
"city": "CITY",
"countryFullname": "COUNTRY",
"subdivisionFullname": "LOCATION",
"addressLine": "ADDRESS",
"country": "ZZ",
"postalCode": "CODE",
"subdivision": "ZZ-ZZ"
},
"contactDetails": {
"firstName": "ACME",
"lastName": "A Company"
}
}
},
"carrierId": "c8a08776-c095-4dec-8553-8f9698d86adc",
"region": "Domestic",
"totalTax": {
"value": "0.00",
"currency": "EUR"
},
"title": "Verzendkosten"
},
"context": {
"metaSiteId": "a41dd7a7-3eb3-4b9f-8adc-c54269f2c15c",
"activationId": "abc22200-647e-4b45-bbd0-a40361e734f2"
},
"channelType": "WEB",
"checkoutCustomFields": {},
"_context": {
"activation": {
"id": "abc22200-647e-4b45-bbd0-a40361e734f2"
},
"configuration": {
"id": "fc6c6dd5-79f0-4665-b03d-3240e9b456b5"
},
"app": {
"id": "1380b703-ce81-ff05-f115-39571d94dfcd"
},
"action": {
"id": "38547a47-f18a-c78b-c75f-7b352487ccc0"
},
"trigger": {
"key": "wix_e_commerce-order_placed"
}
},
"appliedDiscounts": [],
"attributionSource": "UNSPECIFIED",
"contact": {
"name": {
"first": "ACME",
"last": "A Company"
},
"emails": [
{
"id": "a29b2e40-b597-4b03-9808-51fee2438002",
"tag": "UNTAGGED",
"email": "somewhere@acme.forever",
"primary": true
}
],
"phone": "MOBILE",
"email": "somewhere@acme.forever"
},
"weightUnit": "KG",
"priceSummary": {
"tax": {
"value": "0.00",
"currency": "EUR"
},
"total": {
"value": "0.01",
"currency": "EUR"
},
"subtotal": {
"value": "0.01",
"currency": "EUR"
},
"discount": {
"value": "0",
"currency": "EUR"
},
"shipping": {
"value": "0.00",
"currency": "EUR"
}
},
"id": "eb923ff8-8412-48f4-92b5-32ff2802b072",
"buyerEmail": "somewhere@acme.forver",
"status": "APPROVED",
"contactId": "ea9a011f-ad94-4d65-ab1a-5d3cc3976a6a",
"billingInfo": {
"address": {
"city": "CITY",
"countryFullname": "COUNTRY",
"subdivisionFullname": "LOCATION",
"addressLine": "ADDRESS",
"country": "ZZ",
"postalCode": "POSTAL",
"subdivision": "ZZ-ZZ"
},
"contactDetails": {
"firstName": "ACME",
"lastName": "A Company"
}
},
"fulfillmentStatusesAggregate": [],
"catalogs": [
"215238eb-22a5-4c36-9e7b-e7c08025e04e"
],
"currency": "EUR",
"balanceSummary": {
"balance": {
"value": "0.00",
"currency": "EUR"
},
"paid": {
"value": "0.01",
"currency": "EUR"
},
"refunded": {
"value": "0",
"currency": "EUR"
}
},
"checkoutId": "4228237f-27d3-48f3-a23e-9d6336e3af8f",
"buyerLanguage": "nl",
"createdDate": "2024-04-11T05:48:46.514Z"
}
}
]It is therefore recommended that you work with a certified Wix partner, and create a reduced payload as demonstrated below.
[
{
"data": {
"orderNumber": "10002",
"shippingInfo": {
"logistics": {
"deliveryTime": "3-5 werkdagen",
"shippingDestination": {
"address": {
"city": "CITY",
"countryFullname": "COUNTRY",
"subdivisionFullname": "LOCATION",
"addressLine": "ADDRESS",
"country": "ZZ",
"postalCode": "CODE",
"subdivision": "ZZ-ZZ"
},
"contactDetails": {
"firstName": "ACME",
"lastName": "A Company"
}
}
},
"carrierId": "c8a08776-c095-4dec-8553-8f9698d86adc" /* Would need to define Blue Sage in Wix */,
"region": "Domestic",
"title": "Verzendkosten"
},
"contact": {
"name": {
"first": "ACME",
"last": "A Company"
},
"emails": [
{
"id": "a29b2e40-b597-4b03-9808-51fee2438002",
"tag": "UNTAGGED",
"email": "somewhere@acme.forever",
"primary": true
}
],
"phone": "MOBILE",
"email": "somewhere@acme.forever"
},
"buyerEmail": "somewhere@acme.forver",
}
}
}
]The correspond schema is defined below.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "BlueSageCouriersWixReceiver",
"description": "Blue Sage Couriers Wix Receiver Wehbook 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"
},
"orderNumber": {
"description": "Order Identifier",
"type": "string",
"$comment": "Retrieve from {{ data.orderNumber }} - Required"
},
"shipping_firstName": {
"description": "Shipping Firstname",
"type": "string",
"$comment": "Retrieve via {{ shippingInfo.contact.name.first }} - Required"
},
"shipping_lastName": {
"description": "Shipping Lastname or Surname",
"type": "string",
"$comment": "Retrieve via {{ shippingInfo.contact.name.last }} - Required"
},
"shipping_phone": {
"description": "Shipping Phone",
"type": "string",
"$comment": "Retrieve via {{ shippingInfo.contact.phone }} - Required"
},
"shipping_email": {
"description": "Shipping Phone",
"type": "string",
"$comment": "Retrieve via {{ shippingInfo.contact.email }} - Required"
},
"shipping_address1": {
"description": "Shipping Address Line 1",
"type": "string",
"$comment": "Retrieve via {{ shippingInfo.logistics.shippingDestination.address }} - Required"
},
"shipping_city": {
"description": "Shipping City",
"type": "string",
"$comment": "Retrieve via {{ shippingInfo.logistics.shippingDestination.city }} - Required"
},
"shipping_state": {
"description": "Shipping State or Province",
"type": "string",
"$comment": "Retrieve via {{ shippingInfo.logistics.shippingDestination.subdivisionFullname }} - Required"
},
"shipping_country": {
"description": "Shipping Country",
"type": "string",
"$comment": "Retrieve via {{ shippingInfo.logistics.shippingDestination.countryFullname }} - Optional - only service South Africa"
},
"shipping_postcode": {
"description": "Shipping Postal Code",
"type": "string",
"$comment": "Retrieve via {{ shippingInfo.logistics.shippingDestination.postalCode }} - Required"
},
"dispatchReadyDate": {
"description": "Dispatch Ready Date",
"type": "string",
"$comment": "Retrieve via {{ shippingInfo.logistics.deliveryTime }} - Optional"
},
"dispatchReadyDateMask": {
"description": "Shipping Firstname",
"type": "string",
"$comment": "Enter Date Mask (example YYYYMMDD) - Optional - must be coded based on {{ shippingInfo.logistics.deliveryTime }} date schema implemented"
},
"taskAction": {
"description": "Task Action",
"type": "string",
"$comment": "Required Enter either UPDATE or CANCELLED"
}
},
"required": [
"senderID",
"orderNumber",
"shipping_firstName",
"shipping_lastName",
"shipping_phone",
"shipping_email",
"shipping_address1",
"shipping_city",
"shipping_state",
"shipping_postcode",
"taskAction"
]
}Receiving Feedback
You have two 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 semi-realtime via Webhooks. This require some coding in Wix, 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.