Backend API: Create an order comment

Last updated: September 15, 2026

Edit on GitHub

The order-comments resource of the Backend API lets Back Office integrations add a comment to a placed order. This document describes how to create a comment and which validations the request has to pass.

Installation

The endpoints are provided by the OrderExperienceManagement module. For details on installing it, see Install the Orders Backend API feature.

Create an order comment

To add a comment to an order, send the request:

POST /orders/{{orderReference}}/comments

PATH PARAMETER	DESCRIPTION
{{orderReference}}	Reference of the order to comment on. To get it, retrieve orders.

Request

HEADER KEY	HEADER VALUE	REQUIRED	DESCRIPTION
Authorization	string	✓	Alphanumeric string that authorizes the Back Office user to send requests to protected resources. Get it by authenticating as a Back Office user.

Request sample: add a comment to an order

POST https://glue-backend.mysprykershop.com/orders/DE--1234/comments

{
    "data": {
        "type": "order-comments",
        "attributes": {
            "message": "Customer asked to hold the shipment until Friday."
        }
    }
}

ATTRIBUTE	TYPE	REQUIRED	DESCRIPTION
message	String	✓	The comment body. Trimmed, then required to be 1 to 5000 characters.

Author is set automatically

The comment is attributed to the operator whose access token was used. username cannot be supplied by the client—a value sent for it is ignored.

Response

Response sample: create an order comment

{
    "data": {
        "id": "DE--1234",
        "type": "order-comments",
        "attributes": {
            "orderReference": "DE--1234",
            "message": "Customer asked to hold the shipment until Friday.",
            "username": "Admin Spryker",
            "createdAt": "2026-08-27 15:12:03.000000",
            "updatedAt": "2026-08-27 15:12:03.000000"
        }
    }
}

ATTRIBUTE	TYPE	DESCRIPTION
orderReference	String	Order the comment belongs to.
message	String	The comment body.
username	String	Display name of the operator who wrote the comment.
createdAt	String	Timestamp the comment was created at.
updatedAt	String	Timestamp the comment was last updated at.

Possible errors

STATUS	CODE	REASON
404	N/A	No order with the specified `orderReference`.
422	N/A	The message is blank, or longer than 5000 characters.

| 401 | N/A | The Authorization header is missing, or the access token is invalid or expired. | | 403 | N/A | The authenticated Back Office user is not allowed to access the order-comments resource. |

To view generic errors and status codes of the Backend API, see Backend API request and response reference.