Synthesized mode has been used to help upgrade implementations from the previous version of eCommerce into Unified Commerce. It is used to get shipment status data from the Order API and displays this information on the My Account page of the storefront, where the shipment data is not normally available by default.
Synthesized mode is usually no longer needed post-upgrade except in some use cases, such as to get the balance that needs to be refunded on an order that has been over-collected.
Implementing Synthesized Mode in the Theme
In the core theme, all the code is set to look at packages and not shipments. A pull request (PR) is available in which JavaScript makes a synthesized Order API request to get shipment data instead of package data. This gives a better overview of shipment states rather than through the default packages. Once the JavaScript is implemented, it makes an API request with the mode parameter to get the data. The PR is a basic example but since order pricing data is not reliable in synthesized mode, you should only use this as a reference and implement it in their own way for accurate information.
Synthesized Order API Calls
To retrieve shipments from the storefront with synthesized mode, such as to display shipment information on My Account page, you need to pass mode: synthesized as a query parameter in the Get Order API.
The API converts each shipment into a package and displays that in the packages object on the order. The packages object does not include the Shipment IDs, but it shows the shipment statuses that you need to display for the customer.
This response will change some of the pricing in the response due to how it calculates the amount remaining for payment based on differences in the shipment data accessible to the non-synthesized Get Order API vs. the synthesized Get Order API. If you want proper pricing and shipment information, you have to make a regular and synthesized API call. Only use synthesized for getting shipment statuses.
Non-Synthesized Mode Example
The following response is received from non-synthesized Order API calls.
The response has been edited down to only show the relevant fields.
[{
"orderNumber": 3849,
"packages": []
}
]Synthesized Mode Example
The following response is received from the Synthesized Mode:
The response has been edited down to only show the relevant fields.
[{
"orderNumber": 3849,
"packages": [
{
"shippingMethodCode": "cd59632375e845e5beb9ae0601178238",
"shippingMethodName": "FREE",
"hasLabel": false,
"id": "2e48878a938d43c3af84af2e010de4bf",
"status": "NotFulfilled",
"items": [
{
"productCode": "20001605",
"quantity": 7,
"fulfillmentItemType": "Physical",
"lineId": 1
}
],
"auditInfo": {
"updateDate": "2022-10-04T20:23:19.000Z",
"createDate": "2022-10-04T20:23:19.000Z",
"updateBy": "",
"createBy": ""
},
"availableActions": [
"Ship",
"Fulfill"
],
"changeMessages": []
},
{
"shippingMethodCode": "cd59632375e845e5beb9ae0601178238",
"shippingMethodName": "FREE",
"hasLabel": false,
"id": "f33febfe4d8f4b9b9d7aaf2e010de4bf",
"status": "NotFulfilled",
"items": [
{
"productCode": "20001605",
"quantity": 1,
"fulfillmentItemType": "Physical",
"lineId": 2
}
],
"auditInfo": {
"updateDate": "2022-10-04T20:41:58.000Z",
"createDate": "2022-10-04T20:23:19.000Z",
"updateBy": "",
"createBy": ""
},
"availableActions": [
"Ship",
"Fulfill"
],
"changeMessages": []
}
],
}]