Submission notes provide a simple way to store additional information against a submission in WS Form. Notes appear in the Submissions admin sidebar and can be used to record actions, integration results, audit information, or other developer-defined data.

WS Form provides two PHP helper functions for working with submission notes:

• wsf_submit_note_add() to create a note
• wsf_submit_notes_get() to retrieve notes for a submission

These helper functions are available when WS Form is active. You will need a known submission ID, such as one obtained from wsf_submit_get_object() or from an action that provides $submit->id.

Add A Note

Use wsf_submit_note_add() to add a note to a submission.

Function

wsf_submit_note_add(
	$submit_id,
	$content = '',
	$meta = array(),
	$user_id = 0,
	$user_name = '',
	$locked = false
);

Parameters

Return Value

Returns the newly created note ID as an integer.

Add A Note For The Current User

The following example adds a note attributed to the currently logged-in WordPress user.

$note_id = wsf_submit_note_add(
	123,
	'Customer record successfully updated.',
	array(),
	get_current_user_id()
);

Add A Note With Meta Values

Use the values key in $meta to store label/value pairs shown with the note.

$meta = array(

	'values' => array(

		'CRM ID'        => 'C-48291',
		'Status'        => 'Success',
		'Response Time' => '245 ms'
	)
);

$note_id = wsf_submit_note_add(
	123,
	'CRM synchronization completed.',
	$meta,
	get_current_user_id()
);

Add A Note With Buttons

Use the buttons key in $meta to add action links below the note meta values in the admin. Buttons are display-only; they cannot be added or edited from the Submissions UI.

$meta = array(

	'values' => array(

		'Status' => 'Completed',
		'Amount' => '$49.00'
	),

	'buttons' => array(

		array(

			'url'    => admin_url( 'admin.php?page=my-plugin-history&submit_id=123' ),
			'label'  => 'View history',
			'type'   => 'primary',
			'target' => '_blank'
		),

		array(

			'url'   => admin_url( 'admin.php?page=my-plugin-settings' ),
			'label' => 'Settings',
			'type'  => 'secondary'
		)
	)
);

$note_id = wsf_submit_note_add(
	123,
	'Conversion tracked for this submission.',
	$meta,
	0,
	'My Custom Integration',
	true
);

Each button supports the following keys:

Add A Locked System Note

Use a locked note when recording audit information or system events that should not be modified.

$meta = array(

	'values' => array(

		'Export ID' => 'EXP-10428'
	)
);

$note_id = wsf_submit_note_add(
	123,
	'Order exported to external system.',
	$meta,
	0,
	'My Custom Integration',
	true
);

In this example:

• $user_id is set to 0.
• $user_name is used as the note author.
• $locked is set to true, preventing the note from being edited or deleted in the admin.

Get Notes

Use wsf_submit_notes_get() to retrieve all notes associated with a submission.

Function

wsf_submit_notes_get( $submit_id );

Parameters

Return Value

Returns an array of note objects in oldest-first order.

Each note object includes the following properties:

Loop Through Submission Notes

The following example retrieves the notes for a submission and outputs the note content and any associated meta values.

$notes = wsf_submit_notes_get( 123 );

foreach ( $notes as $note ) {

	echo '<h3>' . esc_html( $note->content ) . '</h3>';

	$values = (
		isset( $note->meta['values'] ) &&
		is_array( $note->meta['values'] )
	) ? $note->meta['values'] : array();

	if ( ! empty( $values ) ) {

		echo '<ul>';

		foreach ( $values as $key => $value ) {

			echo '<li>';
			echo esc_html( $key ) . ': ' . esc_html( $value );
			echo '</li>';
		}

		echo '</ul>';
	}
}

Meta Data

The $meta parameter is a PHP array with two optional keys: values and buttons.

$meta = array(

	'values' => array(

		'Status'    => 'Completed',
		'Reference' => 'ABC-12345',
		'Duration'  => '180 ms'
	),

	'buttons' => array(

		array(

			'url'   => admin_url( 'admin.php?page=my-plugin-history' ),
			'label' => 'View history',
			'type'  => 'primary'
		)
	)
);

Values are displayed as label/value rows alongside the note in the Submissions admin sidebar.

Buttons are displayed below the values as action links. They are useful for linking to related admin screens, such as conversion history or external records.

Meta values are useful for storing structured information such as:

• Integration reference IDs
• Processing statuses
• Response times
• External record IDs
• Workflow results

The $meta value must be passed as a PHP array.

Locked Notes

By default, submission notes can be edited or deleted from the Submissions admin.

Set the $locked parameter to true to create an immutable note that cannot be edited or deleted in the admin.

Locked notes are useful for:

• Audit trails
• Integration logs
• System-generated events
• Compliance records
• Debugging information that should not be changed

Buttons on locked notes remain clickable in the admin.

Common Use Cases

Submission notes can be used in themes, custom plugins, actions, and other PHP integrations.

Common uses include:

• Adding a note after a submission has been processed.
• Recording CRM or third-party integration results.
• Storing reference IDs returned by external services.
• Recording workflow or validation events.
• Adding buttons that link to related admin pages or external records.
• Building custom admin tools that add context to submissions.
• Creating immutable system or audit notes.

Because notes are attached directly to the submission, they provide a convenient way to keep developer and integration information alongside the original submission record.