Add or edit a note with attachments

A note on a contract also raises a webhook so an integration can react to the comment.

Where you can do this

• Merchant View: Comments (Save)

Before you start

• On create, the caller names the record the note belongs to (reference). The server does not check that the record exists.
• On edit, the note exists. Attachments already on the note stay; adding new ones is this function, removing one is Delete a note or an attachment.

Inputs

The body is { "note": {... } }.

Rules

Checked by the API means Shuttle refuses the request however it is sent; a screen name means only that screen refuses it, and a direct API call would be accepted.

Rule	Checked by	What you see
The fields go inside a note object: {"note": {... }}. The record itself is identified by the id in the URL, not in the body	The API	VALIDATION_ERROR: “API body error: missing note object”
A new note must name the record it belongs to	The API	VALIDATION_ERROR: “Reference required”
A note’s reference cannot be moved: a reference sent on an edit is ignored	The API	none; the note stays on its original record
Text is not required server-side: a note with no text and no attachments is accepted. Merchant View offers Save only when there is text or at least one file. By design: the API allows a file to be attached to a record on its own; the screen treats a comment as something that has been written.	Not the API; Merchant View screen refuses it	Save control not shown
Every attachment needs a file name	The API	VALIDATION_ERROR: “Field fileName is required.”
Every attachment needs content	The API	code “error”: “No content”
An attachment’s media type is always read from its own data:<type>;base64 prefix. A mime_type sent with the attachment is not forwarded to Shuttle, so content that is not such a URI is stored with no type at all and cannot be given one	The API	none; the attachment reports the type in the prefix, or none
A note’s linked_object cannot be set. It is returned on every note and accepted on a save, but Shuttle’s note has no such field and the value is recomputed from reference on read; Merchant View sends it back on every edit and it is dropped	The API	none; linked_object still follows reference
There is no server-side cap on the number or total size of attachments beyond the API’s 10 MB request body limit. Merchant View refuses a comment whose new files exceed about 0.7 MB raw (1 MB once encoded), and shows the message while Save is disabled	Merchant View screen	inline “Sorry! Your comment including all attachments cannot exceed 1mb”, Save disabled
Attachments are added one at a time under a lock on the note; an upload waits up to ten seconds for the lock and holds it for at most fifteen	The API	code INVALID (BOLT-7059) for the upload that timed out; the text and any earlier attachments are already saved
Merchant View offers Edit on a comment only to the user who wrote it. By design: it is a rule for the people using the screen, who do not hold API keys.	Not the API; Merchant View screen hides the control	author menu not shown
On the contract screen Merchant View also requires the contract permission (payment_contract) to edit a comment; adding one needs no permission	Merchant View screen	control hidden
Merchant View shows the comments section only when the comments option is on for the merchant view; the server has no such switch and the API accepts notes regardless	Merchant View screen	section not shown

What happens

• The note is created (id no_...) or updated and returned in full: text, reference, edited, public, created, updated, the creating and updating users, and attachments[] each with an id, name, mime_type, size and a download url. An edited note reports edited true; the creator is never overwritten.
• Files are stored and kept with the note. When public is true, the first attachment is reachable without signing in at the note’s public_url.
• A note on a contract raises the CONTRACT.NOTE webhook, on create and again on every edit. The event names the contract, not the note. Notes on any other record raise no webhook.
• The contract’s audit history gains a CONTRACT.NOTE entry for each save. (The admin guide states that comments are not part of the audit history; that is true of the note’s content, but a contract note does leave this entry.)
• The note appears in the record’s comments immediately; Merchant View reloads the section as soon as the save returns. No email or SMS is sent.

Who can do this

• Roles: Admin and Support.
• Admin app: option comments shows the section; Edit on a comment is offered only to its author, and on the contract screen only with payment_contract; on terminal batch screens only while the batch is open.

Related

• Delete a note or an attachment