update_post_meta() in WordPress: Return Values, prev_value, Arrays & REST

Updated 16 October 2026 · By Abhilash Sahoo, Infyways

$result = update_post_meta( $post_id, $meta_key, $meta_value, $prev_value = '' );

What are the parameters of update_post_meta()?

The signature from the official WordPress developer reference is:

update_post_meta( int $post_id, string $meta_key, mixed $meta_value, mixed $prev_value = '' ): int|bool

Internally, update_post_meta() is a thin wrapper: it swaps a revision ID for its parent and then calls update_metadata( 'post', ... ), the same engine behind user, term and comment meta.

What does update_post_meta() return?

Two practical lessons follow. First, don't treat false as an error: it usually means "nothing to change". Second, WordPress doesn't check that the post exists, so validate the ID yourself or you'll leave orphaned rows in wp_postmeta:

if ( ! get_post( $post_id ) ) {
    return; // avoid orphaned meta
}
$result = update_post_meta( $post_id, 'color', 'blue' );
if ( false === $result && get_post_meta( $post_id, 'color', true ) !== 'blue' ) {
    error_log( 'Saving color failed' ); // a real failure
}

How do I use update_post_meta()? (examples)

Save a custom field on save_post (secure version)

add_action( 'save_post_product', function ( $post_id ) {
    if ( defined( 'DOING_AUTOSAVE' ) && DOING_AUTOSAVE ) return;
    if ( wp_is_post_revision( $post_id ) ) return;
    if ( ! isset( $_POST['iw_price_nonce'] ) || ! wp_verify_nonce( $_POST['iw_price_nonce'], 'iw_save_price' ) ) return;
    if ( ! current_user_can( 'edit_post', $post_id ) ) return;

    if ( isset( $_POST['iw_price'] ) ) {
        $price = sanitize_text_field( wp_unslash( $_POST['iw_price'] ) );
        update_post_meta( $post_id, '_iw_price', $price );
    }
} );

$_POST data is already slashed by WordPress, so wp_unslash() it before sanitizing. update_post_meta() then strips slashes again, so plain text values come out right. See the slashing section below for the case where this goes wrong.

Read the value back

$price = get_post_meta( $post_id, '_iw_price', true ); // single value (string)

Change a page template

update_post_meta( $page_id, '_wp_page_template', 'templates/full-width.php' );

Increment a counter

$views = (int) get_post_meta( $post_id, 'iw_views', true );
update_post_meta( $post_id, 'iw_views', $views + 1 );

Under heavy traffic, two requests can read the same number and both write +1. For accurate counters, use a custom table or an atomic SQL UPDATE.

How does the $prev_value parameter work?

A post can hold several rows with the same key (added with add_post_meta()). $prev_value picks which one to change:

That last row is the classic bug: calling update_post_meta() without $prev_value on a multi-value key silently destroys the other values.

Unique vs multiple values: add_post_meta() and get_post_meta()

Because a missing key returns '', you can't tell "empty" from "not set" with get_post_meta() alone. Use metadata_exists( 'post', $post_id, $key ).

What happens when you save an array?

WordPress serializes arrays and objects on save and unserializes them on read. The real stored value for [12, 15, 18] is a:3:{i:0;i:12;i:1;i:15;i:2;i:18;}.

• get_post_meta( $p, 'gallery', true ) returns the array. With false you get it nested one level deeper ([[12, 15, 18]]), which is a common source of "my array has an extra level" bugs.
• Saving the identical array again returns false. Saving ['12','15','18'] (strings) returns true, because the serialized form differs.
• Scalars come back as strings: 5 → '5', true → '1', false → '' (and the row still exists).
• You can't query inside serialized data with meta_query reliably. If you need to filter by a value, store it in its own key.

Why do backslashes disappear? (wp_slash and JSON)

For historical reasons, update_post_meta() expects the key and value to be slashed, and runs stripslashes() on them before saving. Our test results:

The rule is simple: if a value can contain a backslash (JSON, Windows paths, regex), wrap it in wp_slash(). Values from $_POST are the exception, since they arrive slashed. wp_unslash() them for sanitizing, and pass the result straight to update_post_meta() only if it contains no backslashes you need to keep.

What are protected meta keys (underscore prefix)?

Keys starting with _ are "protected": is_protected_meta( '_price', 'post' ) returns true, and is_protected_meta( 'price', 'post' ) returns false. Protected keys are hidden from the classic Custom Fields meta box, so editors can't change them by accident. That's why WooCommerce uses _price and core uses _wp_page_template and _thumbnail_id (see our guide to getting the featured image URL in PHP). Protection is about the UI only. It isn't security, as the REST test below shows.

How do I delete post meta?

To remove a key from every post, use delete_post_meta_by_key( 'tag' ). Don't set a value to '' when you mean "remove", because that leaves a row behind.

How do I update post meta through the REST API?

Meta only appears in /wp-json/wp/v2/posts/<id> (and in the block editor) after you register it with show_in_rest:

add_action( 'init', function () {
    register_post_meta( 'post', 'iw_price', array(
        'type'              => 'number',
        'single'            => true,
        'show_in_rest'      => true,
        'sanitize_callback' => fn( $value ) => round( (float) $value, 2 ),
        'auth_callback'     => fn() => current_user_can( 'edit_posts' ),
    ) );
    register_post_meta( 'post', 'iw_tags', array(
        'type'         => 'array',
        'single'       => true,
        'show_in_rest' => array( 'schema' => array( 'items' => array( 'type' => 'string' ) ) ),
    ) );
} );

Then send POST /wp-json/wp/v2/posts/4 with {"meta":{"iw_price":19.999,"iw_tags":["a","b"]}}. What we saw:

Three gotchas here that most tutorials miss:

• auth_callback protects writes, not reads. Never register a secret with show_in_rest.
• WordPress passes 4 arguments to sanitize_callback, and strict PHP built-ins like floatval crash. Wrap them in a closure.
• The sanitize_callback also runs on direct PHP calls. Our update_post_meta( 4, 'iw_price', '7.456abc' ) was stored as '7.46'.

Site-wide settings work the same way through register_setting(). See our WordPress get_option() guide for the REST settings endpoint.

Is update_post_meta() slow? (meta cache and performance)

WordPress loads all meta for a post in one query and keeps it in the object cache. We counted $wpdb->num_queries:

• When you loop over IDs you fetched yourself, prime the cache with update_meta_cache( 'post', $ids ). WP_Query does this for you by default (update_post_meta_cache).
• Each changed update_post_meta() clears that post's meta cache. In bulk imports, compare values first or batch your writes.
• wp_postmeta has no index on meta_value, so meta_query filters on large sites get slow. Use a taxonomy or a custom table for data you filter on heavily.
• On a case-insensitive collation (the default, utf8mb4_unicode_520_ci), update_post_meta( $p, 'color2', 'Y' ) updated our existing Color2 row, but get_post_meta( $p, 'color2', true ) returned ''. Keep keys lowercase.

Which hooks fire when post meta is updated?

update_post_meta vs add_post_meta vs update_metadata

What are the most common update_post_meta mistakes?

1. Treating false as failure. An unchanged value also returns false.
2. Overwriting multi-value keys. Leaving out $prev_value overwrites every row.
3. Breaking JSON. Values with backslashes need wp_slash().
4. Using get_post_meta( ..., false ) for an array. It's nested one level deeper, so use true.
5. Skipping nonce and capability checks on save_post, and not skipping autosaves.
6. Saving meta for post IDs that don't exist. WordPress adds the orphan row without complaint.
7. Thinking _keys are private. They're only hidden from the meta box, and REST can still expose them.
8. Running get_post_meta() in a loop without priming the meta cache.
9. Using built-in PHP functions as sanitize_callback, which causes an ArgumentCountError fatal.

Need the current page's slug or title before saving meta for it? See how to get the current page name in WordPress.

Conclusion

update_post_meta() is simple to call but easy to misuse. Treat false as "maybe unchanged", use $prev_value for multi-value keys, wp_slash() anything with backslashes, register keys before using them over REST, and prime the meta cache in loops. If you'd rather have a team build custom fields, meta boxes or a full plugin for you, our WordPress plugin development service can help.