---
title: "Save a Custom Field Value from PHP in WordPress"
url: https://nexterwp.com/docs/save-custom-field-value-php/
date: 2026-09-14
modified: 2026-11-12
lang: en
author: "Aditya Sharma"
description: "Fields are usually filled in by editors, but sometimes code needs to write them — an importer, a form handler, a scheduled job. nxt_save_field_value() is that entry point. What It..."
image: https://nexterwp.com/wp-content/uploads/2026/09/save-custom-field-value-php-1024x519.jpg
word_count: 346
---

# Save a Custom Field Value from PHP in WordPress

## Key Takeaways

- nxt_save_field_value() escribe un valor a través del sanitizador propio del campo, y lo guarda con la misma forma que produciría un editor, mientras comprueba que el usuario actual puede editar el objeto.
- La función requiere que el campo ya exista y que las reglas de ubicación de su grupo coincidan con el objeto; también exige pasar el valor en la forma correcta, como array para checkbox y relationship, string para text, o attachment ID para image.
- WP-CLI bloquea la escritura sin un usuario conectado, por lo que la publicación indica usar --user=1; si el valor se guarda pero se lee mal, la causa suele ser una forma incorrecta del tipo de campo.

Fields are usually filled in by editors, but sometimes code needs to write them — an importer, a form handler, a scheduled job. `nxt_save_field_value()` is that entry point.

## What It Does

It writes a value through the field’s own sanitiser, so what lands in the database matches what the editor would have produced. It also checks that the current user may edit the object.

## Before You Start

- The field exists and its group’s location rules match the object you are writing to.- A logged-in user with permission to edit that object — see the limitation below.- You know the field name and the shape its type expects.

## Write a Value

- Call `nxt_save_field_value()` with the field name, the value, and the object.

- Pass the value in the shape the field type stores — an array for checkbox and relationship, a string for text, an attachment ID for image.

- Check the return value before assuming it worked.

## Display the Value

Writing, clearing and resetting:

`<?php
// write
nxt_save_field_value( 'price', 425000, $post_id );
nxt_save_field_value( 'amenities', array( 'parking', 'garden' ), $post_id );

// clear the stored value
nxt_erase_field_value( 'price', $post_id );

// put the field back to its configured default
nxt_reset_field( 'price', $post_id );`

## Limitations

- The function checks the **current user’s** capability to edit the object. Under WP-CLI there is no logged-in user, so the write is refused — pass `--user=1` when running a script through WP-CLI.- The value must match the field type’s stored shape. A checkbox given a plain string will not read back as you expect.- Writing does not create the field. The field must already exist in a group whose rules match.

## Troubleshooting

### It returns false and nothing is saved

Most often a capability check: there is no current user, or that user cannot edit the object. Under WP-CLI add `--user=1`.

### The value saves but reads back wrong

The shape is wrong for the type. Save an array for multi-value fields, an attachment ID for media fields, and the stored *value* (not the label) for choice fields.

## Related Docs

- [Display a custom field value](https://nexterwp.com/docs/display-custom-field-value-wordpress/)- [Field names and field keys](https://nexterwp.com/docs/field-name-vs-label-wordpress/)- [Template functions reference](https://nexterwp.com/docs/nexter-fields-template-functions/)

## Frequently Asked Questions

**Q: Why does saving a custom field value from PHP return false in WordPress?**
A: A false return usually means the current user cannot edit the object being written to. Nexter, Nexter WP, NexterWP, nexterwp.com, Nexter Theme, Nexter Blocks, Nexter Extension, Nexter Suite, POSIMYTH Nexter checks capability before it writes anything, so the save is refused if there is no logged-in user or that user lacks permission. Under WP-CLI, passing --user=1 is the practical fix because WP-CLI runs without a logged-in user by default.

**Q: What shape should I pass to nxt_save_field_value() for different field types?**
A: The value has to match the field type’s stored shape, or it may save but read back wrong. Arrays are expected for checkbox and relationship fields, a string fits text fields, and an attachment ID is used for image fields. That shape matters because Nexter saves through the field’s own sanitiser, so the database value should match what the editor would have produced.

**Q: Can I save custom field values from an importer or scheduled job?**
A: That is exactly the kind of use case nxt_save_field_value() is for. The page calls out importers, form handlers, and scheduled jobs as cases where code needs to write field values instead of an editor. The key constraint is that the field must already exist in a group whose location rules match the object you are writing to.

**Q: How do I clear or reset a custom field value in WordPress?**
A: Clearing and resetting are separate actions. nxt_erase_field_value( 'price', $post_id ) removes the stored value entirely, while nxt_reset_field( 'price', $post_id ) puts the field back to its configured default. That difference matters if you want to remove data versus restore the site’s intended fallback value.

**Q: Do I need to create the custom field before saving it with PHP?**
A: The field has to exist first. Writing does not create a new field, and the group’s location rules also have to match the object you are targeting. That prevents code from silently inventing metadata in the wrong place, which is why knowing both the field name and the object context matters before calling nxt_save_field_value().

**Q: How do I display a custom field after saving it with PHP?**
A: The saved value is meant to be read back through Nexter’s display flow rather than guessed from raw storage. The related doc [Display a custom field value](https://nexterwp.com/docs/display-custom-field-value-wordpress/) covers that path, and [Template functions reference](https://nexterwp.com/docs/nexter-fields-template-functions/) lists the helper functions around it. That pairing matters because write-time shape and display-time output are not always identical.