WordPress wp_insert_post Example: Create Content Programmatically Safely

Last reviewed: April 26, 2026

Programmatic content creation is common in WordPress plugins and integrations: webhook imports, migration utilities, editorial automation, setup wizards, and custom admin tools all need it. The failure mode is sending an underspecified array into wp_insert_post() and assuming WordPress will infer the rest safely.

This guide shows how to create a post with wp_insert_post() using explicit status, taxonomy input, metadata, error handling, and capability-aware caller logic.

Build an explicit post payload

<?php
$postarr = array(
	'post_type'    => 'post',
	'post_status'  => 'draft',
	'post_title'   => 'Imported Incident Summary',
	'post_content' => 'Initial import body.',
	'post_excerpt' => 'Short import summary.',
	'post_category' => array( 3 ),
	'tags_input'   => array( 'imported', 'review-needed' ),
	'meta_input'   => array(
		'_vulnwp_source' => 'sync-job',
	),
);

Declaring the important fields up front keeps the insert path reviewable. Draft is often a safer default than publish when content is created by automation or by a user action that still needs editorial review.

Insert with WP_Error support

$post_id = wp_insert_post( $postarr, true );

if ( is_wp_error( $post_id ) ) {
	error_log( 'Insert failed: ' . $post_id->get_error_message() );
	return $post_id;
}

Passing true as the second argument is important. Without it, failures can collapse into 0, which hides useful diagnostics.

Control who is allowed to create content

The insert function itself does not magically decide whether the current caller should be creating content in this flow. That decision belongs to the code path that triggers the insert.

if ( ! current_user_can( 'edit_posts' ) ) {
	return new WP_Error( 'forbidden', 'You are not allowed to create posts.' );
}

Keep authorization close to the entry point: admin form handler, AJAX action, REST route, or CLI command wrapper.

Update instead of duplicate when appropriate

If the job should refresh an existing record, pass an ID in the payload. The same function handles inserts and updates.

$postarr['ID']           = $existing_post_id;
$postarr['post_status']  = 'publish';
$postarr['post_content'] = $new_content;

$updated_id = wp_insert_post( $postarr, true );

Production checklist

• Set post type and post status explicitly.
• Pass true to request WP_Error on failure.
• Authorize the caller before creating content.
• Use meta_input and taxonomy input deliberately instead of ad hoc follow-up writes when possible.
• Default automation to draft unless immediate publish is intentionally required.
• Reuse the same function for updates by passing an ID.

Common mistakes

• Publishing automation by default. That can leak incomplete or unreviewed content.
• Ignoring WP_Error. Silent failures are expensive to debug later.
• No caller authorization. The surrounding entry point still needs capability checks.
• Writing ambiguous taxonomy data. IDs are clearer than names for hierarchical taxonomies.
• Creating duplicates instead of updating known records. Use ID when the row already exists.

Related reading

If the insert runs after an admin form submission, pair this with the admin_post guide. If you later save structured post metadata, combine it with the meta box article.

References and further reading

• WordPress Code Reference: wp_insert_post()
• WordPress Code Reference: wp_insert_post hook
• WordPress Code Reference: current_user_can()