# Orders | Developer Documentation

<div id="bkmrk-ordersupdated%3A-mar-2">## Orders

<div><span>Updated: Mar 25, 2026</span></div><div>Payments API introduces two new types of [interactive messages](/books/meta-whatsapp/page/sending-messages-developer-documentation): `order_details` and `order_status`. They are the entrypoint to collect payment in WhatsApp.</div>
<span>`order_details` messages are sent to create an order in the buyer’s WhatsApp client app. This message includes the payment settings used to collect payment and can optionally include an `order` object with itemized products, fees, and discounts. Without the `order` object, you can send a simplified order details message with just the total amount and payment settings. The payment settings will vary depending on the integration type ([Pix](/books/meta-whatsapp/page/offsite-pix-payments-developer-documentation), [payment links](/books/meta-whatsapp/page/payment-links-developer-documentation), [Boleto](/books/meta-whatsapp/page/boleto-developer-documentation), [One Click Payments](/books/meta-whatsapp/page/one-click-payments-developer-documentation)).</span><span>`order_status` messages are sent when businesses update the order status either based on the WhatsApp payment status change notification or based on their internal processes. You can also send a simplified status update without the `order` object.</span><div>![Image](https://support2.chatarchitect.com/uploads/images/gallery/2026-04/embedded-image-pev8y9ir.jpeg)</div><div>When attached to an order details message, orders start in `pending` status. When the merchant has fully fulfilled the order and the buyer should not expect any further updates, it must be marked as `completed`.</div><div id="bkmrk-full-api-reference"><div id="bkmrk-full-api-reference-1"><div>### Full API Reference

</div></div></div><div id="bkmrk-order-details"><div id="bkmrk-order-details-1"><div>#### Order Details

</div></div></div><div>To send an order_details message, businesses must assemble an interactive object of type order_details with the following components:</div><div id="bkmrk-interactive-object"><div id="bkmrk-interactive-object-1"><div>##### Interactive Object

</div></div></div><div><table><thead><tr><th><span>**Field Name**</span></th><th><span>**Optional?**</span></th><th><span>**Type**</span></th><th><span>**Description**</span></th></tr></thead><tbody><tr><td><div><div>type</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Must be `order_details`.</div></div></td></tr><tr><td><div><div>header</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Object</div></div></td><td><div><div>Thumbnail image for order details message. It has the following fields:</div>
<span>`type`: Must be `image`.</span><span>`image`: See [Image Object](#bkmrk-image-object-1).</span><div><div>If the header is not present, the API finds the first product with an image and uses that for the thumbnail image.</div></div></div></td></tr><tr><td><div><div>body</div></div></td><td><div><div>Required</div></div></td><td><div><div>Object</div></div></td><td><div><div>An object with the body of the message. The object contains the following field:</div>
<span>`text` string: The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters.</span></div></td></tr><tr><td><div><div>footer</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Object</div></div></td><td><div><div>An object with the footer of the message. The object contains the following field:</div>
<span>`text` string: **Required** if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters.</span></div></td></tr><tr><td><div><div>action</div></div></td><td><div><div>Required</div></div></td><td><div><div>Action Object</div></div></td><td><div><div>See [Action Object](#bkmrk-action-object-1) below.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-image-object"><div id="bkmrk-image-object-1"><div>##### Image Object

</div></div></div><div><table><thead><tr><th><span>Field Name </span></th><th><span>Optional? </span></th><th><span>Type </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>link</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Url of the image.</div></div></td></tr><tr><td><div><div>provider</div></div></td><td><div><div>Optional</div></div></td><td><div><div>String</div></div></td><td><div><div>Name of the url provider.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-action-object"><div id="bkmrk-action-object-1"><div>##### Action Object

</div></div></div><div><table><thead><tr><th><span>Field Name </span></th><th><span>Optional? </span></th><th><span>Type </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>name</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Must be `review_and_pay`.</div></div></td></tr><tr><td><div><div>parameters</div></div></td><td><div><div>Required</div></div></td><td><div><div>Parameters Object</div></div></td><td><div><div>See [Parameters Object](#bkmrk-parameters-object-1).</div></div></td></tr></tbody></table>

</div><div id="bkmrk-parameters-object"><div id="bkmrk-parameters-object-1"><div>##### Parameters Object

</div></div></div><div><table><thead><tr><th><span>**Field Name**</span></th><th><span>**Optional?**</span></th><th><span>**Type**</span></th><th><span>**Description**</span></th></tr></thead><tbody><tr><td><div><div>reference_id</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Unique identifier for the order or invoice provided by the business. This cannot be an empty string and can only contain English letters, numbers, underscores, dashes, or dots, and should not exceed 60 characters.</div><div>The reference_id must be unique for each order_details message for the same business. If the partner would like to send multiple order_details messages for the same order, invoice, etc. it is recommended to include a sequence number in the reference_id to ensure reference_id uniqueness.</div></div></td></tr><tr><td><div><div>type</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Must be one of `digital-goods` or `physical-goods`.</div></div></td></tr><tr><td><div><div>payment_type</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Must be `br`.</div></div></td></tr><tr><td><div><div>payment_settings</div></div></td><td><div><div>Optional</div></div></td><td><div><div>[Payment Settings Object](#bkmrk-payment-settings-1)</div></div></td><td><div><div>List of payment related configuration objects.</div></div></td></tr><tr><td><div><div>currency</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>ISO 4217 currency code for the order. Must be `BRL` (Brazilian Real).</div></div></td></tr><tr><td><div><div>total_amount</div></div></td><td><div><div>Required</div></div></td><td><div><div>Amount Object</div></div></td><td><div><div>See [Amount Object](#bkmrk-amount-object-1).</div><div><span></span><div>`total_amount.value` must be equal to `order.subtotal.value` + `order.tax.value` + `order.shipping.value` - `order.discount.value`</div></div></div></td></tr><tr><td><div><div>order</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Order Object</div></div></td><td><div><div>See [Order Object](#bkmrk-order-object-1).</div></div></td></tr></tbody></table>

</div><div id="bkmrk-payment-settings"><div id="bkmrk-payment-settings-1"><div>##### Payment Settings

</div></div></div><div><table><thead><tr><th><span>Field Name </span></th><th><span>Optional? </span></th><th><span>Type </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>`type`</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>One of `pix_dynamic_code`, `payment_link`, `boleto`.</div></div></td></tr><tr><td><div><div>One of the following objects: `pix_dynamic_code`, `payment_link`, `boleto`.</div></div></td><td><div><div>Required</div></div></td><td><div><div>Object</div></div></td><td><div><div>Payment instructions which will be displayed to buyers during the checkout process.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-order-object"><div id="bkmrk-order-object-1"><div>##### Order Object

</div></div></div><div><table><thead><tr><th><span>**Field Name**</span></th><th><span>**Optional?**</span></th><th><span>**Type**</span></th><th><span>**Description**</span></th></tr></thead><tbody><tr><td><div><div>status</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Status of the order. Only supported value here is `pending`.</div></div></td></tr><tr><td><div><div>catalog_id</div></div></td><td><div><div>Optional</div></div></td><td><div><div>String</div></div></td><td><div><div>Unique identifier of the Facebook catalog being used by the business.</div></div></td></tr><tr><td><div><div>expiration</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Expiration Object</div></div></td><td><div><div>Expiration for that order. The CTA for payment will be disabled after expiry on the user end. See [Expiration Object](#bkmrk-expiration-object-1).</div></div></td></tr><tr><td><div><div>items</div></div></td><td><div><div>Required</div></div></td><td><div><div>List of Item Objects</div></div></td><td><div><div>List must have at least one item. See [Item Object](#bkmrk-item-object-1).</div></div></td></tr><tr><td><div><div>subtotal</div></div></td><td><div><div>Required</div></div></td><td><div><div>Amount Object</div></div></td><td><div><div>See [Amount Object](#bkmrk-amount-object-1).</div><div><span></span><div>The value **must be equal** to sum of (`item.amount.value` or `item.sale_amount.value`) * `item.quantity`.</div></div><div>The following fields are part of the `subtotal` object:</div><div>`offset` string</div>
<span>**Required.** Must be `100` for `BRL`.</span><div>`value` string</div>
<span>**Required.** Positive integer representing the amount value multiplied by offset. For example, S$12.34. has value 1234</span></div></td></tr><tr><td><div><div>tax</div></div></td><td><div><div>Required</div></div></td><td><div><div>Amount With Description Object</div></div></td><td><div><div>The tax information for this order. Even though the object is required, the amount can be zero. When zero is used, the tax line is not rendered in the client. See [Amount With Description Object](#bkmrk-amount-object-%28with--1).</div></div></td></tr><tr><td><div><div>shipping</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Amount With Description Object</div></div></td><td><div><div>See [Amount Object](#bkmrk-amount-object-%28with--1).</div></div></td></tr><tr><td><div><div>discount</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Discount Object</div></div></td><td><div><div>The discount for the order. See [Discount object](#bkmrk-discount-object-1).</div></div></td></tr></tbody></table>

</div><div id="bkmrk-expiration-object"><div id="bkmrk-expiration-object-1"><div>##### Expiration Object

</div></div></div><div><table><thead><tr><th><span>**Field Name**</span></th><th><span>**Optional?**</span></th><th><span>**Type**</span></th><th><span>**Description**</span></th></tr></thead><tbody><tr><td><div><div>timestamp</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>UTC time in seconds. Minimum threshold is 300 seconds.</div></div></td></tr><tr><td><div><div>description</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Text explanation for when the order will expire. Max character limit is 120 characters.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-item-object"><div id="bkmrk-item-object-1"><div>##### Item Object

</div></div></div><div><table><thead><tr><th><span>**Field Name**</span></th><th><span>**Optional?**</span></th><th><span>**Type**</span></th><th><span>**Description**</span></th></tr></thead><tbody><tr><td><div><div>retailer_id</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Content ID for an item in the order from your catalog.</div></div></td></tr><tr><td><div><div>name</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>The item’s name to be displayed to the user. Cannot exceed 60 characters.</div></div></td></tr><tr><td><div><div>amount</div></div></td><td><div><div>Required</div></div></td><td><div><div>Amount Object</div></div></td><td><div><div>The price per item. See [Amount Object](#bkmrk-amount-object-1).</div></div></td></tr><tr><td><div><div>quantity</div></div></td><td><div><div>Required</div></div></td><td><div><div>Integer</div></div></td><td><div><div>Number of items in this order.</div></div></td></tr><tr><td><div><div>sale_amount</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Amount Object</div></div></td><td><div><div>The discounted price per item. This should be less than the original amount. If included, this field is used to calculate the subtotal amount. See [Amount Object](#bkmrk-amount-object-1).</div></div></td></tr></tbody></table>

</div><div id="bkmrk-discount-object"><div id="bkmrk-discount-object-1"><div>##### Discount Object

</div></div></div><div><table><thead><tr><th><span>**Field Name**</span></th><th><span>**Optional?**</span></th><th><span>**Type**</span></th><th><span>**Description**</span></th></tr></thead><tbody><tr><td><div><div>value</div></div></td><td><div><div>Required</div></div></td><td><div><div>Integer</div></div></td><td><div><div>Positive integer representing the amount value multiplied by offset. For example, 12.34 BRL has value 1234.</div></div></td></tr><tr><td><div><div>offset</div></div></td><td><div><div>Required</div></div></td><td><div><div>Integer</div></div></td><td><div><div>Must be `100` for `BRL`.</div></div></td></tr><tr><td><div><div>description</div></div></td><td><div><div>Optional</div></div></td><td><div><div>String</div></div></td><td><div><div>Max character limit is 60 characters.</div></div></td></tr><tr><td><div><div>discount_program_name</div></div></td><td><div><div>Optional</div></div></td><td><div><div>String</div></div></td><td><div><div>Text used for defining incentivised orders. If order is incentivised, the merchant needs to define this information. Max character limit is 60 characters.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-amount-object"><div id="bkmrk-amount-object-1"><div>##### Amount Object

</div></div></div><div><table><thead><tr><th><span>**Field Name**</span></th><th><span>**Optional?**</span></th><th><span>**Type**</span></th><th><span>**Description**</span></th></tr></thead><tbody><tr><td><div><div>value</div></div></td><td><div><div>Required</div></div></td><td><div><div>Integer</div></div></td><td><div><div>Positive integer representing the amount value multiplied by offset. For example, 12.34 BRL has value 1234.</div></div></td></tr><tr><td><div><div>offset</div></div></td><td><div><div>Required</div></div></td><td><div><div>Integer</div></div></td><td><div><div>Must be `100` for `BRL`.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-amount-object-%28with-"><div id="bkmrk-amount-object-%28with--1"><div>##### Amount Object (With Description)

</div></div></div><div><table><thead><tr><th><span>**Field Name**</span></th><th><span>**Optional?**</span></th><th><span>**Type**</span></th><th><span>**Description**</span></th></tr></thead><tbody><tr><td><div><div>value</div></div></td><td><div><div>Required</div></div></td><td><div><div>Integer</div></div></td><td><div><div>Positive integer representing the amount value multiplied by offset. For example, 12.34 BRL has value 1234.</div></div></td></tr><tr><td><div><div>offset</div></div></td><td><div><div>Required</div></div></td><td><div><div>Integer</div></div></td><td><div><div>Must be `100` for `BRL`.</div></div></td></tr><tr><td><div><div>description</div></div></td><td><div><div>Optional</div></div></td><td><div><div>String</div></div></td><td><div><div>Max character limit is 60 characters.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-order-status"><div id="bkmrk-order-status-1"><div>#### Order Status

</div></div></div><div>To send an order_status message, businesses must assemble an interactive object of type order_status with the following components:</div><div id="bkmrk-interactive-object-3"><div id="bkmrk-interactive-object-4"><div>##### Interactive Object

</div></div></div><div><table><thead><tr><th><span>**Field Name**</span></th><th><span>**Optional?**</span></th><th><span>**Type**</span></th><th><span>**Description**</span></th></tr></thead><tbody><tr><td><div><div>type</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Must be `order_status`.</div></div></td></tr><tr><td><div><div>header</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Object</div></div></td><td><div><div>Optional object for the message’s header for the message.</div></div></td></tr><tr><td><div><div>body</div></div></td><td><div><div>Required</div></div></td><td><div><div>Object</div></div></td><td><div><div>An object with the body of the message. The object contains the following field:</div>
<span>`text` string: The content of the message. Emojis and markdown are supported. Maximum length is 1024 characters.</span></div></td></tr><tr><td><div><div>footer</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Object</div></div></td><td><div><div>An object with the footer of the message. The object contains the following field:</div>
<span>`text` string: **Required** if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length is 60 characters.</span></div></td></tr><tr><td><div><div>action</div></div></td><td><div><div>Required</div></div></td><td><div><div>Action Object</div></div></td><td><div><div>See [Action Object](#bkmrk-action-object-4) below.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-action-object-3"><div id="bkmrk-action-object-4"><div>##### Action Object

</div></div></div><div><table><thead><tr><th><span>Field Name </span></th><th><span>Optional? </span></th><th><span>Type </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>name</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>Must be `review_order`.</div></div></td></tr><tr><td><div><div>parameters</div></div></td><td><div><div>Required</div></div></td><td><div><div>Parameters Object</div></div></td><td><div><div>See [Parameters Object](#bkmrk-parameters-object-4).</div></div></td></tr></tbody></table>

</div><div id="bkmrk-parameters-object-3"><div id="bkmrk-parameters-object-4"><div>##### Parameters Object

</div></div></div><div><table><thead><tr><th><span>Field Name </span></th><th><span>Optional? </span></th><th><span>Type </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>reference_id</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>The unique ID provided in the `order_details` message.</div></div></td></tr><tr><td><div><div>order</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Order Object</div></div></td><td><div><div>See [Order Object](#bkmrk-order-object-4).</div></div></td></tr><tr><td><div><div>payment</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Payment Object</div></div></td><td><div><div>See [Payment Object](#bkmrk-payment-object-1).</div></div></td></tr></tbody></table>

</div><div id="bkmrk-order-object-3"><div id="bkmrk-order-object-4"><div>##### Order Object

</div></div></div><div><table><thead><tr><th><span>Field Name </span></th><th><span>Optional? </span></th><th><span>Type </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>status</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>The new order status. [See supported order status](#bkmrk-supported-order-stat-1).</div></div></td></tr><tr><td><div><div>description</div></div></td><td><div><div>Optional</div></div></td><td><div><div>String</div></div></td><td><div><div>Optional text for sharing status related information in order-details page. Could be useful while sending cancellation. Length should not exceed 120 characters.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-payment-object"><div id="bkmrk-payment-object-1"><div>##### Payment Object

</div></div></div><div><table><thead><tr><th><span>Field Name </span></th><th><span>Optional? </span></th><th><span>Type </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>status</div></div></td><td><div><div>Required</div></div></td><td><div><div>String</div></div></td><td><div><div>The new payment status. [See supported payment status](#bkmrk-supported-payment-st-1).</div></div></td></tr><tr><td><div><div>timestamp</div></div></td><td><div><div>Optional</div></div></td><td><div><div>Integer</div></div></td><td><div><div>Optional epoch timestamp in seconds</div></div></td></tr></tbody></table>

</div><div id="bkmrk-supported-order-stat"><div id="bkmrk-supported-order-stat-1"><div>##### Supported Order Status

</div></div></div><div>Currently we support the following order status values:</div><div><table><thead><tr><th><span>Value </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>`pending`</div></div></td><td><div><div>Order is pending / not processed yet.</div></div></td></tr><tr><td><div><div>`processing`</div></div></td><td><div><div>Merchant/partner is fulfilling the order, performing service, etc.</div></div></td></tr><tr><td><div><div>`partially-shipped`</div></div></td><td><div><div>Part of the products in order have been shipped by the merchant.</div></div></td></tr><tr><td><div><div>`shipped`</div></div></td><td><div><div>All the products in order have been shipped by the merchant.</div></div></td></tr><tr><td><div><div>`completed`</div></div></td><td><div><div>The order is completed and no further action is expected from the user or the partner/merchant.</div></div></td></tr><tr><td><div><div>`canceled`</div></div></td><td><div><div>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.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-supported-payment-st"><div id="bkmrk-supported-payment-st-1"><div>##### Supported Payment Status

</div></div></div><div>Currently we support the following payment status values:</div><div><table><thead><tr><th><span>Value </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>`pending`</div></div></td><td><div><div>Payment is pending.</div></div></td></tr><tr><td><div><div>`captured`</div></div></td><td><div><div>Payment was successfully captured. Receiving this payment status will update the order bubble to include the “paid” label (with green checkmark).</div></div></td></tr><tr><td><div><div>`failed`</div></div></td><td><div><div>Payment failed.</div></div></td></tr></tbody></table>

</div><div id="bkmrk-errors-and-statuses"><div id="bkmrk-errors-and-statuses-1"><div>### Errors and Statuses

</div></div></div><div>These are the relevant errors for the WhatsApp Payments API:</div><div><table><thead><tr><th><span>Error Code </span></th><th><span>Description </span></th></tr></thead><tbody><tr><td><div><div>`2040 - Message is not supported`</div></div></td><td><div><div>The message you are trying to send cannot be received by this user</div></div></td></tr><tr><td><div><div>`2046 - Order status invalid transition`</div></div></td><td><div><div>The order status cannot be updated from the existing value to the new one</div></div></td></tr><tr><td><div><div>`2047 - Order cancellation failure`</div></div></td><td><div><div>The order could not be cancelled</div></div></td></tr></tbody></table>

</div><div>For a comprehensive list with detailed descriptions of error codes and HTTP status codes, please refer to our [Error Codes](/documentation/business-messaging/whatsapp/support/error-codes) document.</div></div>