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.

1
{
2
  "id": "note_live_a1b2c3d4e5f6g7h8",
3
  "content": "High-value customer — escalate billing issues to enterprise support.",
4
  "entity_id": "cus_live_x1y2z3a4b5c6d7e8",
5
  "created_at": "2024-09-01T10:00:00Z",
6
  "updated_at": "2024-09-01T10:00:00Z"
7
}

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.

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.

1
{
2
  "content": "Migrated from legacy system. Original plan: Professional v2.",
3
  "entity_id": "sub_live_a1b2c3d4e5f6g7h8"
4
}

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 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.

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

See 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 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.

1
{
2
  "content": "Migrated from legacy system. Now on Professional v3 as of 2024-09."
3
}

Returns 404 if the note does not exist.

See 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 for the full API reference.

Limits