> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pazy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoice Comment Add API

> Add a comment to a specific invoice, with optional @-mentions of users

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
Content-Type: application/json
```

## Request

**Content-Type:** `application/json`

### Path Parameters

| Parameter   | Type   | Required | Description                                    |
| ----------- | ------ | -------- | ---------------------------------------------- |
| `invoiceId` | string | Yes      | Unique identifier of the invoice to comment on |

### Body Parameters

| Parameter | Type   | Required | Description                                                                                               |
| --------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
| `comment` | string | Yes      | The comment text (1–1500 characters). May contain `@<userId>` mentions — see [Mentions](#mentions) below. |

### Mentions

Comments support user mentions in the form `@<userId>` (the user's id / slug). When rendered via the [Invoice Comments API](/apis/invoice-comments), valid `@<userId>` tokens are replaced with the user's display name (e.g., `@John Doe`). Mentions whose user id does not exist in your organization are kept in the text as-is — they are not rejected.

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pazy.io/v1.0/invoice/<invoiceId>/comment \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "comment": "Please review this invoice @<userId>"
    }'
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/invoice/<invoiceId>/comment', {
    method: 'POST',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      comment: 'Please review this invoice @<userId>'
    })
  });

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/invoice/<invoiceId>/comment"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  payload = { "comment": "Please review this invoice @<userId>" }

  response = requests.post(url, headers=headers, json=payload)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field    | Type    | Description                                       |
| -------- | ------- | ------------------------------------------------- |
| `ok`     | boolean | Indicates whether the request was successful      |
| `insert` | boolean | Indicates the comment was inserted on the invoice |

### Response Example

```json theme={null}
{
  "ok": true,
  "insert": true
}
```

## Error Responses

### Missing Comment

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body: must have required property 'comment'"
  }
}
```

### Invalid Comment Type

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_TYPE",
    "message": "Comment should be a string"
  }
}
```

### Invoice Not Found

**HTTP Status:** `404 Not Found`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice not found"
  }
}
```

### Access Denied

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied: You can only view your own invoices or invoices where you are the vendor owner"
  }
}
```

Returned when the caller is not an admin / bookkeeper, did not create the invoice, and is not the owner of its vendor.

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

### Internal Error

**HTTP Status:** `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}
```

## Best Practices

* Keep comments under 1500 characters — longer text is rejected with `VALIDATION_ERROR`
* Use `@<userId>` to address specific users — fetch the id from the [User List API](/apis/user-list) or [User Details API](/apis/user-details)
* The comment author is the user tied to the API key — there is no `userId` field in the body
* Use the [Invoice Comments API](/apis/invoice-comments) to retrieve the thread with mentions resolved to user names