From 51d92d4363df3c1963b4d0d47aaa64d2d29bd4fe Mon Sep 17 00:00:00 2001 From: Corey McKrill <916023+coreymckrill@users.noreply.github.com> Date: Tue, 4 Feb 2025 17:09:19 -0800 Subject: [PATCH] Add docs for new email-related order actions endpoints --- source/includes/wp-api-v3/_order-actions.md | 188 +++++++++++++++++++- source/includes/wp-api-v3/_orders.md | 12 ++ 2 files changed, 192 insertions(+), 8 deletions(-) diff --git a/source/includes/wp-api-v3/_order-actions.md b/source/includes/wp-api-v3/_order-actions.md index c551bd9..597857f 100644 --- a/source/includes/wp-api-v3/_order-actions.md +++ b/source/includes/wp-api-v3/_order-actions.md @@ -2,11 +2,11 @@ The order actions API allows you to perform specific actions with existing orders like you can from the Edit Order screen in the web app. -_Note: currently only one action is available, other actions will be introduced at a later time._ +_Note: currently only some actions are available, other actions will be introduced at a later time._ ## Send order details to customer ## -This endpoint allows you to trigger an email to the customer with the details of their order, if the order contains a customer email address. +This endpoint allows you to trigger an email to the customer with the details of their order. In case the order doesn't yet have a billing email set, you can specify an email recipient. However, if the order does have an existing billing email, this will return an error, unless you also specify that the existing email should be overwritten by using the `force_email_update` parameter. ### HTTP request ### @@ -19,11 +19,20 @@ This endpoint allows you to trigger an email to the customer with the details of ```shell curl -X POST https://example.com/wp-json/wc/v3/orders/723/actions/send_order_details \ - -u consumer_key:consumer_secret + -u consumer_key:consumer_secret \ + -d '{ + "email": "somebody@example.com", + "force_email_update": true + }' ``` ```javascript -WooCommerce.post("orders/723/actions/send_order_details") +const data = { + email: "somebody@example.com", + force_email_update: true +}; + +WooCommerce.post("orders/723/actions/send_order_details", data) .then((response) => { console.log(response.data); }) @@ -34,23 +43,38 @@ WooCommerce.post("orders/723/actions/send_order_details") ```php post('orders/723/actions/send_order_details')); +$data = [ + 'email' => 'somebody@example.com', + 'force_email_update' => true, +]; + +print_r($woocommerce->post('orders/723/actions/send_order_details', $data)); ?> ``` ```python -print(wcapi.post("orders/723/actions/send_order_details").json()) +data = { + "email": "somebody@example.com", + "force_email_update": true +} + +print(wcapi.post("orders/723/actions/send_order_details", data).json()) ``` ```ruby -woocommerce.post("orders/723/actions/send_order_details").parsed_response +data = { + "email": "somebody@example.com", + "force_email_update": true +} + +woocommerce.post("orders/723/actions/send_order_details", data).parsed_response ``` > JSON response examples: ```json { - "message": "Order details sent to woo@example.com, via REST API." + "message": "Billing email updated to somebody@example.com. Order details sent to somebody@example.com, via REST API." } ``` @@ -63,3 +87,151 @@ woocommerce.post("orders/723/actions/send_order_details").parsed_response } } ``` + +## Send order notification email to customer ## + +This endpoint allows you to trigger an email to a customer about the status of their order. This is similar to the [`send_order_details`](#send-order-details-to-customer) endpoint, but allows you to specify which email template to send, based on which email templates are relevant to the order. For example, an order that is on hold has the `customer_on_hold_order` template available. A completed order that also has a partial refund has both the `customer_completed_order` and `customer_refunded_order` templates available. Specifying the `customer_invoice` template is the same as using the `send_order_details` endpoint. + +### HTTP request ### + +
+
+ POST +
/wp-json/wc/v3/orders/<id>/actions/send_email
+
+
+ +```shell +curl -X POST https://example.com/wp-json/wc/v3/orders/723/actions/send_email \ + -u consumer_key:consumer_secret \ + -d '{ + "template_id": "customer_completed_order", + "email": "somebody@example.com", + "force_email_update": true + }' +``` + +```javascript +const data = { + template_id: "customer_completed_order", + email: "somebody@example.com", + force_email_update: true +}; + +WooCommerce.post("orders/723/actions/send_email", data) + .then((response) => { + console.log(response.data); + }) + .catch((error) => { + console.log(error.response.data); + }); +``` + +```php + 'customer_completed_order', + 'email' => 'somebody@example.com', + 'force_email_update' => true, +]; + +print_r($woocommerce->post('orders/723/actions/send_email', $data)); +?> +``` + +```python +data = { + "template_id": "customer_completed_order", + "email": "somebody@example.com", + "force_email_update": true +} + +print(wcapi.post("orders/723/actions/send_email", data).json()) +``` + +```ruby +data = { + "template_id": "customer_completed_order", + "email": "somebody@example.com", + "force_email_update": true +} + +woocommerce.post("orders/723/actions/send_email", data).parsed_response +``` + +> JSON response examples: + +```json +{ + "message": "Billing email updated to somebody@example.com. Email template "Completed order" sent to somebody@example.com, via REST API." +} +``` + +```json +{ + "code": "woocommerce_rest_invalid_email_template", + "message": "customer_completed_order is not a valid template for this order.", + "data": { + "status": 400 + } +} +``` + +## Get available email templates for an order ## + +This endpoint allows you to retrieve a list of email templates that are available for the specified order. You can also get this data embedded in the response for the [`orders` endpoint](#list-all-orders). + +### HTTP request ### + +
+
+ GET +
/wp-json/wc/v3/orders/<id>/actions/email_templates
+
+
+ +```shell +curl -X GET https://example.com/wp-json/wc/v3/orders/723/actions/email_templates \ + -u consumer_key:consumer_secret +``` + +```javascript +WooCommerce.get("orders/723/actions/email_templates") + .then((response) => { + console.log(response.data); + }) + .catch((error) => { + console.log(error.response.data); + }); +``` + +```php +get('orders/723/actions/email_templates')); +?> +``` + +```python +print(wcapi.get("orders/723/actions/email_templates").json()) +``` + +```ruby +woocommerce.post("orders/723/actions/email_templates").parsed_response +``` + +> JSON response examples: + +```json +[ + { + "id": "customer_completed_order", + "title": "Completed order", + "description": "Order complete emails are sent to customers when their orders are marked completed and usually indicate that their orders have been shipped." + }, + { + "id": "customer_invoice", + "title": "Order details", + "description": "Order detail emails can be sent to customers containing their order information and payment links." + } +] +``` diff --git a/source/includes/wp-api-v3/_orders.md b/source/includes/wp-api-v3/_orders.md index e3dc650..2ef2292 100644 --- a/source/includes/wp-api-v3/_orders.md +++ b/source/includes/wp-api-v3/_orders.md @@ -1018,6 +1018,12 @@ woocommerce.get("orders").parsed_response { "href": "https://example.com/wp-json/wc/v3/orders" } + ], + "email_templates": [ + { + "embeddable": true, + "href": "http://example.com/wp-json/wc/v3/orders/723/actions/email_templates" + } ] } }, @@ -1162,6 +1168,12 @@ woocommerce.get("orders").parsed_response "href": "https://example.com/wp-json/wc/v3/orders" } ], + "email_templates": [ + { + "embeddable": true, + "href": "http://example.com/wp-json/wc/v3/orders/723/actions/email_templates" + } + ], "customer": [ { "href": "https://example.com/wp-json/wc/v3/customers/26"