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.

FAQs

What does update_post_meta return?

The new meta ID (int) if the key didn’t exist, true if an existing value changed, and false on failure or when the new value equals the stored one.

Why does update_post_meta return false?

Most often because the value is identical to what’s stored (including 5 vs "5"). It also returns false for a post ID of 0, an empty key, a $prev_value that doesn’t match, or a filter that blocks the write.

Does update_post_meta create the key if it doesn’t exist?

Yes. It behaves like add_post_meta() and returns the new meta ID.

Does update_post_meta check that the post exists?

No. In our test, update_post_meta( 999999, 'x', 'y' ) returned a meta ID for a post that doesn’t exist. Check with get_post() first.

How do I update only one of several values with the same key?

Pass the current value as the fourth argument: update_post_meta( $id, 'mood', 'excited', 'sad' ).

Can I store an array with update_post_meta?

Yes. WordPress serializes it automatically. Read it back with get_post_meta( $id, $key, true ).

Why are backslashes removed from my meta value?

update_post_meta() runs stripslashes() on input. Wrap the value in wp_slash() to keep backslashes in JSON or file paths.

What is the difference between update_post_meta and add_post_meta?

update_post_meta() adds or overwrites. add_post_meta() always adds a new row, unless $unique is true and the key already exists.

How do I update post meta via the REST API?

Register the key with register_post_meta() and show_in_rest => true, then send {"meta":{"key":"value"}} to /wp-json/wp/v2/posts/<id> as an authenticated user. Unregistered keys are ignored.

Does update_post_meta work on revisions?

If you pass a revision ID, the meta is saved on the parent post. In our test, the revision itself got nothing.

Is calling get_post_meta many times slow?

Not for one post. All its meta loads in one query and is then cached. Across many posts, prime the cache with update_meta_cache(), or let WP_Query do it.

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.