diff --git a/src/pages/config.md b/src/pages/config.md index 5056d7b7f..eeae7c9d0 100644 --- a/src/pages/config.md +++ b/src/pages/config.md @@ -155,6 +155,7 @@ - [Custom email](/rest/saas-integrations/custom-email/index.md) - [Gift card accounts](/rest/saas-integrations/gift-card-accounts/index.md) - [Login as Customer](/rest/saas-integrations/login-as-customer/index.md) + - [Order management](/rest/saas-integrations/order-management/index.md) - [S3 uploads](/rest/saas-integrations/s3-uploads/index.md) - [Introduction](/graphql/index.md) - [Usage](/graphql/usage/index.md) diff --git a/src/pages/rest/saas-integrations/custom-email/index.md b/src/pages/rest/saas-integrations/custom-email/index.md index 3dba5c0de..cfee71b18 100644 --- a/src/pages/rest/saas-integrations/custom-email/index.md +++ b/src/pages/rest/saas-integrations/custom-email/index.md @@ -1,6 +1,6 @@ --- title: Email triggering through REST -description: Learn how to trigger transactional emails using the REST API for Adobe Commerce as a Cloud Service. +description: Learn how to trigger transactional emails and manage custom email templates using the REST API for Adobe Commerce as a Cloud Service. keywords: - REST - Integration @@ -97,6 +97,169 @@ The API returns HTTP 200 on successful send. The `reply_to_email` field is only Example: `"message": "Email template with ID \"999\" does not exist."` +## Manage custom email templates + +Use the following endpoints to list, retrieve, and create custom email templates from the REST API. + +| Method | Endpoint | Description | +| --- | --- | --- | +| `GET` | `/V1/custom-email/templates` | List custom email templates, returning each template's ID, code, subject, and type. | +| `GET` | `/V1/custom-email/templates/{id}` | Retrieve a single template, including its body and styles. | +| `POST` | `/V1/custom-email/templates` | Create a custom email template and return its server-assigned ID. | + + + +Use the `template_id` returned by these endpoints with `POST /V1/custom-email/send` instead of looking up the ID manually. + +### List custom email templates + +Use the following endpoint to list all custom email templates. + +#### Endpoint + +- **URL** - `GET /rest/V1/custom-email/templates` + +The endpoint accepts standard `searchCriteria` parameters for pagination, sorting, and filtering. When filtering on `template_type`, filter against the raw numeric column (`1` for text, `2` for HTML) rather than the label in the response. + +#### Response fields + +| Field | Type | Description | +| --- | --- | --- | +| `template_id` | integer | Usable as-is with `POST /V1/custom-email/send`. | +| `template_code` | string | Template name. | +| `template_subject` | string | Template subject, as raw, unrendered directive source. | +| `template_type` | string | `html` or `text`. | +| `added_at` | string | Creation timestamp. | +| `modified_at` | string | Last-modified timestamp. | + +#### Example request + +```http +GET /rest/V1/custom-email/templates?searchCriteria[pageSize]=20&searchCriteria[currentPage]=1 +``` + +#### Example response (HTTP 200) + +```json +{ + "items": [ + { + "template_id": 5, + "template_code": "Abandoned Cart Reminder", + "template_subject": "You left something behind", + "template_type": "html", + "added_at": "2026-06-01 12:34:56", + "modified_at": "2026-06-02 09:10:11" + } + ], + "search_criteria": { + "page_size": 20, + "current_page": 1 + }, + "total_count": 1 +} +``` + +### Retrieve a custom email template + +Use the following endpoint to retrieve a single custom email template by its ID. + +#### Endpoint + +- **URL** - `GET /rest/V1/custom-email/templates/{id}` + +The response includes every field from the list response, plus: + +| Field | Type | Description | +| --- | --- | --- | +| `template_text` | string | Raw, unrendered template body. Directives such as `{{var}}` and `{{trans}}` are preserved, so the value can be sent back verbatim when creating another template. | +| `template_styles` | string | CSS for the template. Empty string for text templates. | + +#### Example request + +```http +GET /rest/V1/custom-email/templates/5 +``` + +#### Example response (HTTP 200) + +```json +{ + "template_id": 5, + "template_code": "Abandoned Cart Reminder", + "template_subject": "{{trans \"You left something behind\"}}", + "template_type": "html", + "template_text": "{{template config_path=\"design/email/header_template\"}}...", + "template_styles": "", + "added_at": "2026-06-01 12:34:56", + "modified_at": "2026-06-02 09:10:11" +} +``` + +#### Error responses + +- **HTTP 404 – Template not found** + + Returned when no custom template matches the given `id`. + +### Create a custom email template + +Use the following endpoint to create a new custom email template. + +#### Endpoint + +- **URL** - `POST /rest/V1/custom-email/templates` + + + +Commerce returns HTTP 200 (not 201) on success, consistent with other Commerce REST endpoints. + +#### Request body + +Wrap the template fields in a `template` object. + +- **template_code** (string, required) – Unique template name. Maximum 150 characters. +- **template_subject** (string, required) – Maximum 200 characters. May contain directive syntax, as described in [Supported template scenarios](#supported-template-scenarios). +- **template_text** (string, required) – Raw template body. Directives are stored as-is and are not rendered at creation time. +- **template_type** (string, optional) – `html` (default) or `text`. +- **template_styles** (string, optional) – CSS for the template. Ignored, and forced to an empty string, when `template_type` is `text`. + +The API ignores any value supplied for `template_id`, `added_at`, or `modified_at`, Commerce assigns these automatically. + + + +The API does not accept `template_sender_name`, `template_sender_email`, `orig_template_code`, or `orig_template_variables`. These fields are either inert for email templates or used only by the Admin template editor. + +#### Example request + +```json +{ + "template": { + "template_code": "Abandoned Cart Reminder", + "template_subject": "You left something behind", + "template_text": "

Hi {{var customer.name}}, your cart misses you.

", + "template_styles": ".greeting { color: #333; }", + "template_type": "html" + } +} +``` + +#### Success response (HTTP 200) + +The response returns the created template in the same shape as [Retrieve a custom email template](#retrieve-a-custom-email-template), including the server-assigned `template_id`. + +#### Error responses + +- **HTTP 400 – Validation error** + + Returned for a missing required field, a value that exceeds its length limit, or an invalid `template_type`. + +- **HTTP 409 – Duplicate template code** + + Returned when a custom template with the same `template_code` already exists. Commerce does not create a duplicate row. + + Example: `"message": "A custom email template with code \"my_code\" already exists."` + ## Supported template scenarios The following template features are supported in both the **email body** and the **template subject**: diff --git a/src/pages/rest/saas-integrations/index.md b/src/pages/rest/saas-integrations/index.md index 91ac14626..00293f6fb 100644 --- a/src/pages/rest/saas-integrations/index.md +++ b/src/pages/rest/saas-integrations/index.md @@ -12,4 +12,5 @@ Review the following topics to learn more about REST APIs available only on Adob - [Custom email](custom-email/index.md) - [Gift card accounts](gift-card-accounts/index.md) - [Login as Customer](login-as-customer/index.md) +- [Order management](order-management/index.md) - [S3 uploads](s3-uploads/index.md) diff --git a/src/pages/rest/saas-integrations/order-management/index.md b/src/pages/rest/saas-integrations/order-management/index.md new file mode 100644 index 000000000..1505a9acb --- /dev/null +++ b/src/pages/rest/saas-integrations/order-management/index.md @@ -0,0 +1,279 @@ +--- +title: Order Management REST Endpoints +description: Learn how to manage the full order chain and edit existing orders programmatically with the order management REST APIs in Adobe Commerce as a Cloud Service. +keywords: + - REST + - Integration +--- + + + +# Order management API + +Adobe Commerce as a Cloud Service provides REST APIs for advanced order operations that go beyond the standard order endpoints. Use these APIs to manage the full chain of orders produced by order edits and to edit an existing order programmatically. + +These two capabilities work together: editing an order produces a chain of linked orders, and the order chain endpoints let you continue to act on that order by its original ID. + +## Manage the full order chain + +When you edit an order, Commerce cancels the original order and creates a new child order that is linked to its predecessor by the original order's increment ID. Across multiple edits, these orders form an order chain. The order chain endpoints let integrations act on an order using its ID and automatically resolve the operation across the full chain of edited orders, so you do not have to track the latest child order yourself. + + + +This feature is experimental and must be enabled by Adobe. To request access, contact your Adobe Commerce Customer Success Manager or create a support ticket. + +The `orderChain` endpoints extend the standard order management endpoints, so each request and response body matches its standard `/V1/order/{id}/...` counterpart. + +| Method | Endpoint | Description | Role resource | +| --- | --- | --- | --- | +| `POST` | `/V1/orderChain/{orderId}/invoice` | Create an invoice for the order, resolving the items to invoice across the order chain. | `Magento_Sales::invoice` | +| `POST` | `/V1/orderChain/{id}/cancel` | Cancel the current order in the chain. | `Magento_Sales::cancel` | +| `POST` | `/V1/orderChain/{id}/hold` | Place the order on hold. | `Magento_Sales::hold` | +| `POST` | `/V1/orderChain/{id}/unhold` | Remove the hold from the order. | `Magento_Sales::unhold` | +| `POST` | `/V1/orderChain/{id}/emails` | Send an order email notification. | `Magento_Sales::emails` | +| `POST` | `/V1/orderChain/{id}/comments` | Add a comment to the order. | `Magento_Sales::comment` | +| `GET` | `/V1/orderChain/{id}/comments` | Retrieve the order comments. | `Magento_Sales::actions_view` | +| `GET` | `/V1/orderChain/{id}/statuses` | Retrieve the current order status. | `Magento_Sales::actions_view` | + +### Order chain examples + +The following examples call each `orderChain` endpoint using order ID `42`. When the specified order is part of a chain, Commerce automatically resolves the request to the latest order in that chain. + +#### Example: create an invoice + +Request: + +```http +POST /rest/V1/orderChain/42/invoice +``` + +Request body: + +```json +{ + "items": [ + { + "order_item_id": 3, + "qty": 1 + } + ], + "notify": true, + "comment": { + "comment": "Invoice created after payment confirmation.", + "is_visible_on_front": 1 + } +} +``` + +The response returns the ID of the new invoice: + +```json +31 +``` + +#### Example: cancel an order + +Request: + +```http +POST /rest/V1/orderChain/42/cancel +``` + +The response confirms the cancellation: + +```json +true +``` + +#### Example: place an order on hold + +Request: + +```http +POST /rest/V1/orderChain/42/hold +``` + +The response confirms the hold: + +```json +true +``` + +#### Example: release an order from hold + +Request: + +```http +POST /rest/V1/orderChain/42/unhold +``` + +The response confirms the order was released from hold: + +```json +true +``` + +#### Example: send an order email + +Request: + +```http +POST /rest/V1/orderChain/42/emails +``` + +The response confirms the notification was sent: + +```json +true +``` + +#### Example: add a comment to an order + +Request: + +```http +POST /rest/V1/orderChain/42/comments +``` + +Request body: + +```json +{ + "statusHistory": { + "comment": "Contacted the customer to confirm the delivery window.", + "is_customer_notified": 1, + "is_visible_on_front": 1, + "parent_id": 42, + "status": "processing" + } +} +``` + +The response confirms the comment was added: + +```json +true +``` + +#### Example: retrieve order comments + +Request: + +```http +GET /rest/V1/orderChain/42/comments +``` + +The response returns the comments for every order in the chain: + +```json +{ + "items": [ + { + "comment": "Contacted the customer to confirm the delivery window.", + "created_at": "2026-07-20 14:32:10", + "entity_id": 12, + "entity_name": "order", + "is_customer_notified": 1, + "is_visible_on_front": 1, + "parent_id": 42, + "status": "processing" + } + ], + "search_criteria": {}, + "total_count": 1 +} +``` + +#### Example: retrieve the order status + +Request: + +```http +GET /rest/V1/orderChain/42/statuses +``` + +The response returns the status of the latest order in the chain: + +```json +"processing" +``` + +### Filter order documents by original order ID + +The following `GET` endpoints support an `order_original_id` search filter: + +* `GET /V1/invoices` +* `GET /V1/shipments` +* `GET /V1/creditmemo` +* `GET /V1/returns` + +Filtering by `order_original_id` returns documents for the entire order chain, not just a single order. The following example returns every invoice in the chain for the original order ID `100000042`: + +```http +GET /V1/invoices?searchCriteria[filterGroups][0][filters][0][field]=order_original_id&searchCriteria[filterGroups][0][filters][0][value]=100000042 +``` + +## Edit orders + +The following REST endpoints replicate the Commerce Admin **Edit Order** feature, allowing integrations to edit an existing order programmatically. Editing an order copies it into a new cart, then submits the modified cart as a new order that replaces the original. + + + +This feature is disabled by default and must be enabled by Adobe. To request access, contact your Adobe Commerce Customer Success Manager or create a support ticket. + +| Method | Endpoint | Description | +| --- | --- | --- | +| `POST` | `/V1/orders/{orderId}/edit/start` | Copy the order into a new editable cart and return the cart ID. | +| `POST` | `/V1/orders/{orderId}/edit/submit` | Submit the modified cart as a new order and cancel the original order. | + +Both endpoints require the `Magento_Sales::actions_edit` role resource. + +### Edit an order + +To edit an existing order: + +1. Call `POST /V1/orders/{orderId}/edit/start`. + + Commerce copies the order's items, addresses, shipping method, coupon code, and payment method into a new cart and returns the cart ID. + +1. Modify the cart using the standard cart REST endpoints, such as adding or removing items, updating addresses, or changing the payment method. + +1. Call `POST /V1/orders/{orderId}/edit/submit` with the cart ID in the `quoteId` field. + +The new order inherits the original order's payment method unless you override it through the cart. Commerce creates the new order as a linked replacement for the canceled original and assigns it an increment ID of the form `{original}-1`, `{original}-2`, and so on. + +#### Example: start an edit + +Request: + +```http +POST /rest/V1/orders/42/edit/start +``` + +The response returns the cart ID to modify and submit: + +```json +17 +``` + +#### Example: submit an edit + +Request: + +```http +POST /rest/V1/orders/42/edit/submit +``` + +Request body: + +```json +{ + "quoteId": 17 +} +``` + +The response returns the ID of the new order: + +```json +55 +```