# Add Order Comment

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /v1/managers/store/orders/{order_Id}/add-order-comment:
    post:
      summary: Add Order Comment
      deprecated: false
      description: >-
        The `Add Order Comment` API allows shipping and fulfilment partners to
        post real-time shipment updates directly to an order’s activity. 


        - Partners can add up to `20 comments per order`, each `limited to 100
        characters`. 

        - `Comments are non-editable `and include the app name for clarity. 


        These updates are visible to merchants in the order activity dashboard,
        improving communication and speeding up fulfilment-related issue
        resolution.


        <Accordion title="🔑Scopes" defaultOpen>
            
         `orders.read_write` - Orders Read & Write
         
        </Accordion>
      tags:
        - Default module/Apps/Merchant APIs/Orders
      parameters:
        - name: order_Id
          in: path
          description: >-
            The unique identifier of the order for which the comment is being
            added.
          required: true
          example: '59214748'
          schema:
            type: string
        - name: Accept
          in: header
          description: >-
            Specifies the Media Types acceptable for the client. In this case,
            it signals that the client expects a response in the JSON format.
          required: false
          example: application/json
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            The Authorization token is a unique key given to the third-party
            application (Partner) by Zid. It is used to authenticate the API
            requests made by the Partner application. The token verifies the
            partner's identity and ensures they have permission to access Zid's
            API but does not provide any specific user or store information. It
            should be included in the header of API requests when the partner
            application needs to access Zid's API.
          required: true
          example: '{{Autherization}}'
          schema:
            type: string
        - name: X-manager-Token
          in: header
          description: >-
            This token is used to authenticate and access information related to
            the store. It is obtained through an OAuth mechanism and is required
            to perform operations on the store's data. The `X-Manager-Token`
            should be included in the header of API requests that require
            store-related information.
          required: false
          example: '{{Access-Token}}'
          schema:
            type: string
        - name: Accept-Language
          in: header
          description: >-
            Preferred language for the response. Defaults to `en` if not
            specified.
          required: false
          example: en
          schema:
            type: string
        - name: User-Agent
          in: header
          description: >-
            The User-Agent header contains information about the user agent
            (browser or app) making the request. It allows the server to provide
            a tailored response depending on the user agent's capabilities and
            preferences.
          required: false
          example: >-
            Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML,
            like Gecko) Chrome/89.0.4389.82 Safari/537.36
          schema:
            type: string
        - name: store-id
          in: header
          description: >-
            The unique identifier of the store where the order belongs
            (integer).
          required: false
          example: 123
          schema:
            type: integer
        - name: role
          in: header
          description: The role of the user initiating the request.
          required: false
          example: Manager
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  description: >-
                    The detailed shipment progress message to be added to the
                    order. This comment will be visible to merchants in the
                    order activity.
              required:
                - comment
              x-apidog-orders:
                - comment
              x-apidog-ignore-properties: []
            example:
              comment: Customer asked to delay shipment by one day
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Response returned after updating an order note, including the
                  updated order details.
                required:
                  - status
                  - order
                  - message
                properties:
                  status:
                    type: string
                    description: Response status indicator.
                    examples:
                      - object
                  order:
                    type: object
                    description: Updated order object.
                    required:
                      - id
                      - code
                      - order_status
                      - currency_code
                      - created_at
                      - updated_at
                    properties:
                      id:
                        type: integer
                        description: Order ID.
                        examples:
                          - 59214748
                      invoice_number:
                        type: integer
                        description: Invoice number associated with the order.
                        examples:
                          - 59214748
                      code:
                        type: string
                        description: Unique order code.
                        examples:
                          - AIajhbzS7h
                      store_id:
                        type: integer
                        description: Store identifier.
                        examples:
                          - 3
                      order_url:
                        type: string
                        description: Public URL to view the order invoice.
                        examples:
                          - https://osama.zid.store/o/AIajhbzS7h/inv
                      store_name:
                        type: string
                        description: Store display name.
                        examples:
                          - Mohammed Zayan
                      store_url:
                        type: string
                        description: Store URL.
                        examples:
                          - https://osama.zid.store/
                      order_status:
                        type: object
                        description: Current order status.
                        required:
                          - name
                          - code
                        properties:
                          name:
                            type: string
                            description: Human-readable order status.
                            examples:
                              - New
                          code:
                            type: string
                            description: Order status code.
                            examples:
                              - new
                        x-apidog-orders:
                          - name
                          - code
                        x-apidog-ignore-properties: []
                      display_status:
                        type: object
                        description: Display-specific order status information.
                        properties:
                          id:
                            type: integer
                            examples:
                              - 1
                          code:
                            type: string
                            examples:
                              - new
                          color:
                            type: string
                            examples:
                              - '#3498db'
                          name:
                            type: string
                            examples:
                              - New
                        x-apidog-orders:
                          - id
                          - code
                          - color
                          - name
                        x-apidog-ignore-properties: []
                      currency_code:
                        type: string
                        description: Order currency code.
                        examples:
                          - SAR
                      customer:
                        type: object
                        description: Customer details.
                        properties:
                          id:
                            type: integer
                            examples:
                              - 37
                          name:
                            type: string
                            examples:
                              - Osama Khaled
                          email:
                            type: string
                            examples:
                              - osamakhaled2010@gmail.com
                          mobile:
                            type: string
                            examples:
                              - '966503187421'
                          note:
                            type: string
                            examples:
                              - ''
                          verified:
                            type: integer
                            examples:
                              - 1
                          type:
                            type: string
                            examples:
                              - individual
                        x-apidog-orders:
                          - id
                          - name
                          - email
                          - mobile
                          - note
                          - verified
                          - type
                        x-apidog-ignore-properties: []
                      order_total:
                        type: string
                        description: Order total value as string.
                        examples:
                          - '211.44999892193000'
                      order_total_string:
                        type: string
                        description: Formatted order total with currency.
                        examples:
                          - 211.45 SAR
                      transaction_amount:
                        type: number
                        description: Transaction amount.
                        examples:
                          - 211.44999892193
                      transaction_amount_string:
                        type: string
                        description: Formatted transaction amount.
                        examples:
                          - 211.45 SAR
                      payment_status:
                        type: string
                        description: Payment status of the order.
                        examples:
                          - paid
                      created_at:
                        type: string
                        description: Order creation timestamp.
                        examples:
                          - '2025-10-13 07:53:13'
                      updated_at:
                        type: string
                        description: Order last update timestamp.
                        examples:
                          - '2026-01-21 19:42:31'
                      products:
                        type: array
                        description: List of products included in the order.
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              examples:
                                - f28e9f26-4a9e-4159-bc50-d128ebe41d34
                            name:
                              type: string
                              examples:
                                - ايلف - برايمر ومرطب للوجه 24مل
                            sku:
                              type: string
                              examples:
                                - glow12
                            quantity:
                              type: integer
                              examples:
                                - 1
                            is_taxable:
                              type: boolean
                              examples:
                                - true
                            net_price_with_additions:
                              type: number
                              description: Net price including additions.
                              examples:
                                - 52.17
                            tax_percentage:
                              type: number
                              description: Applied tax percentage.
                              examples:
                                - 0.15
                            total:
                              type: number
                              description: Total product price.
                              examples:
                                - 60
                          x-apidog-orders:
                            - id
                            - name
                            - sku
                            - quantity
                            - is_taxable
                            - net_price_with_additions
                            - tax_percentage
                            - total
                          x-apidog-ignore-properties: []
                      histories:
                        type: array
                        description: Order activity and history logs.
                        items:
                          type: object
                          properties:
                            order_status_name:
                              type: string
                              description: Order status at the time of change.
                              examples:
                                - New
                            changed_by_type:
                              type: string
                              description: Actor type who made the change.
                              examples:
                                - Merchant
                            changed_by_details:
                              type: object
                              description: Details about the change.
                              properties:
                                action:
                                  type: string
                                  examples:
                                    - Comment added
                                by:
                                  type: string
                                  examples:
                                    - Osama
                                comment:
                                  type: string
                                  examples:
                                    - >-
                                      Customer asked to delay shipment by one
                                      day
                              x-apidog-orders:
                                - action
                                - by
                                - comment
                              x-apidog-ignore-properties: []
                            created_at:
                              type: string
                              description: History entry timestamp.
                              examples:
                                - '2026-01-26 09:48:58'
                            humanized_created_at:
                              type: string
                              description: Human-readable time difference.
                              examples:
                                - 1 second ago
                          x-apidog-orders:
                            - order_status_name
                            - changed_by_type
                            - changed_by_details
                            - created_at
                            - humanized_created_at
                          x-apidog-ignore-properties: []
                    x-apidog-orders:
                      - id
                      - invoice_number
                      - code
                      - store_id
                      - order_url
                      - store_name
                      - store_url
                      - order_status
                      - display_status
                      - currency_code
                      - customer
                      - order_total
                      - order_total_string
                      - transaction_amount
                      - transaction_amount_string
                      - payment_status
                      - created_at
                      - updated_at
                      - products
                      - histories
                    x-apidog-ignore-properties: []
                  message:
                    type: object
                    description: Additional response message object.
                    properties:
                      type:
                        type: string
                        examples:
                          - object
                        nullable: true
                      code:
                        type: string
                        examples:
                          - null
                        nullable: true
                      name:
                        type: string
                        examples:
                          - null
                        nullable: true
                      description:
                        type: string
                        examples:
                          - null
                        nullable: true
                    x-apidog-orders:
                      - type
                      - code
                      - name
                      - description
                    x-apidog-ignore-properties: []
                x-apidog-orders:
                  - status
                  - order
                  - message
                x-apidog-ignore-properties: []
          headers: {}
          x-apidog-name: OK
        '401':
          description: ''
          content:
            application/json:
              schema:
                type: object
                description: >-
                  Response returned when the request cannot be authenticated
                  because the required credentials are missing, invalid, or
                  expired.
                properties:
                  status:
                    type: string
                    description: Indicates the overall status of the API response.
                    examples:
                      - error
                  message:
                    type: object
                    description: >-
                      Contains structured details explaining why the request
                      could not be authenticated.
                    properties:
                      type:
                        type: string
                        description: Indicates the category of the response message.
                        examples:
                          - error
                      code:
                        type: string
                        description: >-
                          A machine-readable code identifying the authentication
                          error. Returns null when no specific code is
                          available.
                        examples:
                          - UNAUTHORIZED
                        nullable: true
                      name:
                        type: string
                        description: >-
                          A short, human-readable title describing the
                          authentication error. Returns null when no title is
                          available.
                        examples:
                          - Unauthorized
                        nullable: true
                      description:
                        type: string
                        description: >-
                          A human-readable explanation of why the request could
                          not be authenticated. Returns null when no detailed
                          explanation is available.
                        examples:
                          - >-
                            Authentication credentials are missing, invalid, or
                            expired.
                        nullable: true
                    required:
                      - type
                      - code
                      - name
                      - description
                    x-apidog-orders:
                      - type
                      - code
                      - name
                      - description
                    x-apidog-ignore-properties: []
                required:
                  - status
                  - message
                x-apidog-orders:
                  - status
                  - message
                examples:
                  - status: error
                    message:
                      type: error
                      code: UNAUTHORIZED
                      name: Unauthorized
                      description: >-
                        Authentication credentials are missing, invalid, or
                        expired.
                x-apidog-ignore-properties: []
              examples:
                '1':
                  summary: Example 1
                  value:
                    status: error
                    message:
                      type: error
                      code: ERROR_SESSION_MISSING
                      name: Sorry
                      description: Please login first.
                '2':
                  summary: Example 2
                  value:
                    status: error
                    message:
                      type: error
                      code: ERROR_SESSION_INVALID
                      name: Sorry
                      description: Login session expired. Please login again.
                '3':
                  summary: Example 3
                  value:
                    status: error
                    message:
                      type: error
                      code: ERROR_SESSION_INVALID
                      name: Sorry
                      description: Invalid authentication
          headers: {}
          x-apidog-name: Unauthorized
        '500':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    description: Status of the error.
                  message:
                    $ref: '#/components/schemas/ResponseEnvelopMessage'
                required:
                  - status
                  - message
                x-apidog-orders:
                  - status
                  - message
                x-apidog-ignore-properties: []
              example:
                status: error
                message:
                  type: error
                  code: MSG_HIDDEN
                  name: Error
                  description: Internal Server Error
          headers: {}
          x-apidog-name: Internal Server error
      security: []
      x-apidog-folder: Default module/Apps/Merchant APIs/Orders
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/613905/apis/api-17440706-run
components:
  schemas:
    ResponseEnvelopMessage:
      type: object
      properties:
        type:
          type: string
          description: Type of response message returned by the API.
          examples:
            - success
        code:
          type: string
          description: Response code returned by the API, if available.
          examples:
            - MSG_POPUP_OK
          nullable: true
        name:
          type: string
          description: Name or title of the response message, if available.
          examples:
            - Coupons
          nullable: true
        description:
          type: string
          description: Detailed description of the response message, if available.
          examples:
            - Coupons created successfully
          nullable: true
      required:
        - type
        - code
        - name
        - description
      description: Additional response metadata.
      x-apidog-orders:
        - type
        - code
        - name
        - description
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
  securitySchemes: {}
servers:
  - url: https://api.zid.sa/
    description: Prod Env
security: []

```