Magento 2: How do I notify a customer about an order status change done via the REST Api?

Question

I'm using the rest API

.../index.php/rest/V1/orders/561/

in order to update my order status:

Payload (POST):

{
  "entity": {
    "entity_id": 561,
    "state": "new",
    "status": "pending"
  }
}

That works fine, but it's not triggering an order status email. Looking into the full payload I don't see any option to trigger the email. Triggering the comments API is triggering a email but it is not the status change email. Any ideas?

Answer 1

You can use the salesOrderManagementV1 to add a comment to an order email and send an email:

POST /V1/orders/{id}/comments
POST /V1/orders/{id}/emails

Some details from the code:

<route url="/V1/orders/:id/emails" method="POST">
    <service class="Magento\Sales\Api\OrderManagementInterface" method="notify"/>
    <resources>
        <resource ref="Magento_Sales::sales" />
    </resources>
</route>

You can also add a comment in that email:

<route url="/V1/orders/:id/comments" method="POST">
    <service class="Magento\Sales\Api\OrderManagementInterface" method="addComment"/>
    <resources>
        <resource ref="Magento_Sales::sales" />
    </resources>
</route>

Digging into the API code:

/**
 * Adds a comment to a specified order.
 *
 * @param int $id The order ID.
 * @param \Magento\Sales\Api\Data\OrderStatusHistoryInterface $statusHistory Status history comment.
 * @return bool
 */
public function addComment($id, \Magento\Sales\Api\Data\OrderStatusHistoryInterface $statusHistory);

/**
 * Emails a user a specified order.
 *
 * @param int $id The order ID.
 * @return bool
 */
public function notify($id);

Answer 2

We have been updating the order status while setting comments with salesOrderManagementV1 as per the Swagger reference. Setting it with an empty comment still triggers the email, but with comments it's optional based on the POST body content:

{
  "statusHistory": {
    "comment": "string",
    "created_at": "string",
    "entity_id": 0,
    "entity_name": "string",
    "is_customer_notified": 0,
    "is_visible_on_front": 0,
    "parent_id": 0,
    "status": "string",
    "extension_attributes": {}
  }
}