Send order status template message | Developer Documentation
Send order status template message
Updated: Nov 14, 2025
Overview
An Order status template is a template with interactive components that extends the call-to-action button to support updating order status through a template. It allows the businesses to update the order status outside of the customer session window in use cases such as charging the card for past order and updating about a shipment on order placed in the past.
Upon receiving the payment signals, the businesses must update the order status to keep the user up to date. Currently we support the following order status values
| Value | Description |
|---|---|
pending | User has not successfully paid yet |
processing | User payment authorized, merchant/partner is fulfilling the order, performing service, etc. |
partially-shipped | A portion of the products in the order have been shipped by the merchant |
shipped | All the products in the order have been shipped by the merchant |
completed | The order is completed and no further action is expected from the user or the partner/merchant |
canceled | The partner/merchant would like to cancel the order_details message for the order/invoice. The status update will fail if there is already a successful or pending payment for this order_details message |
Creating an order status template
To create an order status template, the business needs a business portfolio with a WhatsApp Business Account, and access to the WhatsApp Manager.
In WhatsApp Manager > Account tools:
create templateSelect Utility category to expand Order details message optionEnter the desired template name and supported localelocales selected there will be an equal number of template variants and businesses need to fill in the template details in respective locale.Please fill in template components such as Body and optional footer text and submit.Once submitted, templates will be categorized as per the guidelines and undergo the approval process refrain from having marketing content as part of template components.The template will be approved or rejected after the template components are verified by the system.
ACTIVEACTIVE to PAUSED or DISABLED based on customer feedback and engagement. We recommend that you monitor status changes and take appropriate actions whenever such change occurs.
Creating an order status template using template creation APIs
To create a template through API and understand the general syntax, required categories and
components please refer to our Templates document. All the guidelines outlined above in creating templates apply through API as well.
Order status template is categorized as “Utility” template and apart from ‘name’ and ‘language’ of
choice, it has general template components such as BODY, FOOTER and additionally sub category as “ORDER_STATUS”.
POST https://graph.facebook.com/<API_VERSION>/<WHATSAPP_BUSINESS_BUSINESS_ID>/message_templates
{
"name": "<TEMPLATE_NAME>",
"language": "<LANGUAGE_AND_LOCALE_CODE>",
"category": "UTILITY",
"sub_category": "ORDER_STATUS",
"components": [
{
"type": "BODY",
"text": "<TEMPLATE_BODY_TEXT>"
},
{
"type": "FOOTER",
"text": "<TEMPLATE_FOOTER_TEXT>"
}
]
}
Sending order status template message
Order status template message allows the businesses to send update on the status of the
order as template component parameters.
To send an order status template message, make a
POST call to /<PHONE_NUMBER_ID>/messages
endpoint and attach a message object with type=template. Then, add a template object with a
order_status component and parameters with latest status on order with order reference-id.For example, the following sample describes how to send
shipped status on the placed order.curl -X POST \
'https://graph.facebook.com/<API_VERSION>/<FROM_PHONE_NUMBER_ID>/messages' \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
-d '{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "<PHONE_NUMBER>",
"type": "template",
"template":
{
"name": "<TEMPLATE_NAME>",
"language":
{
"policy": "deterministic",
"code": "<LANGUAGE_AND_LOCALE_CODE>"
},
"components":
[
{
"type": "order_status",
"parameters": [{
"type": "order_status",
"order_status":
{
"reference_id": "reference_id_value",
"order":
{
"status": "processing | partially_shipped | shipped | completed | canceled",
"description": "<OPTIONAL_DESCRIPTION>"
}
}
}]
}
]
}
}
Upon sending an
order_status message with an invalid transition, you will receive an error webhook with the error code 2046 and message New order status was not correctly transitioned.Canceling an order
An order can be canceled by sending an
order_status message with the status canceled. The customer cannot pay for an order that is canceled. The customer receives an order_status message and the order details page is updated to show that the order is canceled and the Continue button removed. The optional text shown below Order canceled on the order details page can be specified using the description field in the order_status message.An order can be canceled only if the user has not already paid for the order. If the user has paid and the business sends a order_status message with canceled status will receive an error webhook with error code
2047 and message Could not change order status to 'canceled'.
No comments to display
No comments to display