Customer notes

Add internal notes to a customer.

Create a note

POST /customers/{externalId}/notes

Scope: customers.write

Adds a note to the customer. text may be plain text or simple HTML (paragraphs, lists, bold and similar). Scripts and event attributes are removed. Because the text is stored as HTML, special characters in plain text come back encoded (for example & as &).

Path parameters

Parameter	Type	Required	Description
`externalId`	string	required	Your customer ID, as sent in `customer.external_id`. Case-sensitive. URL-encode special characters. max length 191

Request body

Field	Type	Required	Description
`text`	string	required	Text of the note, plain text or simple HTML. max length 65535
`notification`	integer \| null	optional	When the note is shown as a notice: `0` never, `1` when opening the customer or an order and when creating an order, `2` only in the customer view. one of: `0`, `1`, `2`, `null` · default `0`

Example request

curl -X POST "https://shop.example.com/api/v1/customers/u-55871/notes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Customer prefers delivery in the afternoon.",
  "notification": 0
}'

Responses

201 Created The note was created.

{
  "data": {
    "id": 501,
    "customer_id": 9021,
    "text": "<p>Customer prefers delivery in the afternoon.</p>",
    "notification": 0,
    "created_at": "2026-10-14T14:02:11+02:00"
  }
}

Response fields

Field	Type	Required	Description
`data`	object	required
`id`	integer	required
`customer_id`	integer	required	Our customer number.
`text`	string	required	The stored text as cleaned HTML.
`notification`	integer	required	one of: `0`, `1`, `2`
`created_at`	string (date-time) \| null	required

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}

403 Forbidden The API key is valid but lacks a scope this endpoint needs. details.required lists the scopes the endpoint requires, details.missing the ones your key lacks. Ask the shop operator to add the scope.

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key is missing a required scope.",
    "details": {
      "required": [
        "orders.write"
      ],
      "missing": [
        "orders.write"
      ]
    }
  }
}

404 Not Found The path does not exist, the API is not enabled on this system, the order does not belong to the shop of your API client, or the customer, address or label value is not known to your API client.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "details": []
  }
}

422 Unprocessable Content The request data is invalid. details lists every problem at once: per field a list of {code, message}. Field names use dots for nesting, for example value_ids.1 is the second entry of value_ids (counting from 0).

{
  "error": {
    "code": "validation_failed",
    "message": "The request payload is invalid.",
    "details": {
      "street": [
        {
          "code": "required",
          "message": "The street field is required."
        }
      ],
      "country": [
        {
          "code": "unknown_country",
          "message": "The selected country is invalid."
        }
      ]
    }
  }
}

429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}

500 Internal Server Error An unexpected error occurred on our side. Retry later.

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.