add_post_meta( int $post_id, string $meta_key, mixed $meta_value, bool $unique = false )

Adds a meta field to the given post.

Description

Post meta data is called "Custom Fields" on the Administration Screen.

Parameters

$post_id

(int) (Required) Post ID.

$meta_key

(string) (Required) Metadata name.

$meta_value

(mixed) (Required) Metadata value. Must be serializable if non-scalar.

$unique

(bool) (Optional) Whether the same key should not be added.

Default value: false

Return

(int|false) Meta ID on success, false on failure.

More Information

Note that if the given key already exists among custom fields of the specified post, another custom field with the same key is added unless the $unique argument is set to true, in which case, no changes are made. If you want to update the value of an existing key, use the update_post_meta() function instead

Character Escaping

Because meta values are passed through the stripslashes() function, you need to be careful about content escaped with \ characters. You can read more about the behavior, and a workaround example, in the update_post_meta() documentation.

Source

File: wp-includes/post.php 

function add_post_meta( $post_id, $meta_key, $meta_value, $unique = false ) {
	// Make sure meta is added to the post, not a revision.
	$the_post = wp_is_post_revision( $post_id );
	if ( $the_post ) {
		$post_id = $the_post;
	}

	return add_metadata( 'post', $post_id, $meta_key, $meta_value, $unique );
}

Uses

Uses Description
wp-includes/revision.php: wp_is_post_revision()

Determines if the specified post is a revision.
wp-includes/meta.php: add_metadata()

Adds metadata for the specified object.

Used By

Used By Description
wp-includes/post.php: wp_check_for_changed_dates()

Check for changed dates for published post objects and save the old date.
wp-admin/includes/class-wp-privacy-policy-content.php: WP_Privacy_Policy_Content::get_suggested_policy_text()

Check for updated, added or removed privacy policy information from plugins.
wp-admin/includes/class-wp-privacy-policy-content.php: WP_Privacy_Policy_Content::_policy_page_updated()

Update the cached policy info when the policy page is updated.
wp-includes/class-wp-customize-manager.php: WP_Customize_Manager::trash_changeset_post()

Trash or delete a changeset post.
wp-includes/post.php: wp_add_trashed_suffix_to_post_name_for_post()

Adds a trashed suffix for a given post.
wp-admin/includes/image.php: wp_generate_attachment_metadata()

Generate attachment meta data and create image sub-sizes for images.
wp-admin/includes/media.php: media_sideload_image()

Downloads an image from the specified URL, saves it as an attachment, and optionally attaches it to a post.
wp-admin/includes/post.php: wp_write_post()

Creates a new post from the “Write Post” form using $_POST information.
wp-admin/includes/post.php: add_meta()

Add post meta data defined in $_POST superglobal for post with given ID.
wp-includes/functions.php: do_enclose()

Check content for video and audio links to add as enclosures.
wp-includes/post.php: _publish_post_hook()

Hook to schedule pings and enclosures when a post is published.
wp-includes/post.php: wp_check_for_changed_slugs()

Check for changed slugs for published post objects and save the old slug.
wp-includes/post.php: wp_insert_post()

Insert or update a post.
wp-includes/post.php: wp_trash_post()

Move a post or page to the Trash
wp-includes/post.php: wp_trash_post_comments()

Moves comments for a post to the Trash.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::add_enclosure_if_new()

Adds an enclosure to a post if it’s new.
wp-includes/class-wp-xmlrpc-server.php: wp_xmlrpc_server::set_custom_fields()

Set custom fields for post.

Changelog

Version Description
1.5.0 Introduced.

© 2003–2021 WordPress Foundation
Licensed under the GNU GPLv2+ License.
https://developer.wordpress.org/reference/functions/add_post_meta