> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paymentkit.com/guides/integration/notes/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paymentkit.com/_mcp/server.

# Notes

> Attach freeform text notes to any entity in PaymentKit — customers, subscriptions, invoices, and more.

## Overview

Notes let you store a single free-text annotation on any PaymentKit entity. Unlike custom fields, notes are unstructured and unconstrained — a plain string you can use for internal comments, support context, or anything your team needs.

Each entity can have **at most one note per account**. Attempting to create a second note for the same entity within the same account returns `409 Conflict`.

```json
{
  "id": "note_live_a1b2c3d4e5f6g7h8",
  "content": "High-value customer — escalate billing issues to enterprise support.",
  "entity_id": "cus_live_x1y2z3a4b5c6d7e8",
  "created_at": "2024-09-01T10:00:00Z",
  "updated_at": "2024-09-01T10:00:00Z"
}
```

You can retrieve a note either by its own ID (`GET /api/{account_id}/notes/{note_id}`) or directly by the entity it is attached to (`GET /api/{account_id}/notes/by-entity/{entity_id}`).

# Supported entities

Notes can be attached to any entity using its external ID. The table below shows common examples; because `entity_id` is a free-form string field, any entity's external ID is accepted.

| Entity         | External ID prefix |
| -------------- | ------------------ |
| Customer       | `cus_`             |
| Subscription   | `sub_`             |
| Invoice        | `in_`              |
| Payment Intent | `pi_`              |
| Product        | `prod_`            |
| Price          | `price_`           |

Pass the entity's external ID as `entity_id` when creating or looking up a note.

# Create a note

`POST /api/{account_id}/notes/`

Creates a new note linked to an entity. Returns `200 OK` with the created note on success.

```json
{
  "content": "Migrated from legacy system. Original plan: Professional v2.",
  "entity_id": "sub_live_a1b2c3d4e5f6g7h8"
}
```

The response includes the note's `id`, `content`, `entity_id`, `created_at`, and `updated_at` fields.

If a note already exists for the entity, the request returns `409 Conflict`.

See [Create Note](/api-reference/api-reference/notes/create-note) for the full API reference.

# Get a note

## By entity

`GET /api/{account_id}/notes/by-entity/{entity_id}`

Retrieves the note attached to the given entity. Returns `404` if no note exists.

```bash
curl "https://app.paymentkit.com/api/{account_id}/notes/by-entity/sub_live_a1b2c3d4e5f6g7h8" \
  -H "Authorization: Bearer {api_token}"
```

See [Get Note by Entity](/api-reference/api-reference/notes/get-note-by-entity) for the full API reference.

## By note ID

`GET /api/{account_id}/notes/{note_id}`

Retrieves a note directly by its ID. Returns `404` if the note does not exist.

See [Get Note](/api-reference/api-reference/notes/get-note) for the full API reference.

# Update a note

`PUT /api/{account_id}/notes/{note_id}`

Replaces the note's content. The entire `content` field is replaced — there is no partial update.

```json
{
  "content": "Migrated from legacy system. Now on Professional v3 as of 2024-09."
}
```

Returns `404` if the note does not exist.

See [Update Note](/api-reference/api-reference/notes/update-note) for the full API reference.

# Delete a note

`DELETE /api/{account_id}/notes/{note_id}`

Deletes the note. Returns `204 No Content` on success, `404` if not found.

After deletion, you can create a new note on the same entity.

See [Delete Note](/api-reference/api-reference/notes/delete-note) for the full API reference.

# Limits

| Limit              | Value             |
| ------------------ | ----------------- |
| Notes per entity   | 1                 |
| Content max length | No enforced limit |