Field values

acpt/list-meta-field-values, acpt/get-meta-field-value, acpt/save-meta-field-value, acpt/append-meta-field-value, acpt/delete-meta-field-value

Category: acpt-content-data · Default capability: edit_posts

These five abilities are different from every other ability in this integration: they don't manage a definition (a post type, a field, a form…) with a natural name. Instead, they read and write the value stored for one field on one specific location — a post, a term, a user, a comment, an option page, or a WooCommerce product attribute.

Ability	What it does
acpt/list-meta-field-values	Returns field values for a location
acpt/get-meta-field-value	Returns the value of a single field for a location
acpt/save-meta-field-value	Creates or updates the value of a single field for a location
acpt/append-meta-field-value	Appends a row to a Repeater field for a location
acpt/delete-meta-field-value	Deletes the value of a single field for a location

The "location" parameter

Every ability in this group accepts the same six optional location properties. Exactly one must be provided per call:

Property	Type	Use when…
post_id	integer	reading/writing a value stored on a post
term_id	integer	…on a taxonomy term
user_id	integer	…on a user
comment_id	integer	…on a comment
option_page	string	…on an option page (its menu slug)
wc_product_attribute	integer	…on a WooCommerce product attribute

These abilities are thin wrappers over ACPT's get_acpt_fields() / get_acpt_field() / save_acpt_meta_field_value() / append_acpt_meta_field_value() / delete_acpt_meta_field_value() functions, which validate their arguments against a strict, internal whitelist. Any key not listed on this page is silently rejected — the call fails closed rather than erroring loudly, so double-check parameter names if a call unexpectedly fails.

acpt/list-meta-field-values

Input

Property	Type	Required	Description
(location)		Yes	Exactly one of the location properties above
box_name	string	No	If omitted, values from every visible box at that location are returned
format	string	No	complete or only_value
assoc	boolean	No	Key results by field DB name instead of a numeric index
return	string	No	raw or object

$result = wp_get_ability('acpt/list-meta-field-values')->execute([
    'post_id'  => 12,
    'box_name' => 'info',
    'assoc'    => true,
]);

{
  "success": true,
  "message": "Operation completed successfully.",
  "data": {
    "release_date": "2024-11-14",
    "runtime_minutes": 128
  }
}

acpt/get-meta-field-value

Input

Property	Type	Required	Description
(location)		Yes	Exactly one of the location properties above
box_name	string	Yes
field_name	string	Yes
format	string	No	complete or only_value
return	string	No	raw, string, or object

$result = wp_get_ability('acpt/get-meta-field-value')->execute([
    'post_id'    => 12,
    'box_name'   => 'info',
    'field_name' => 'release_date',
]);

{
  "success": true,
  "message": "Operation completed successfully.",
  "data": "2024-11-14"
}

A legitimate field value can itself be false, 0, or an empty string — for example, an unchecked Toggle field. acpt/get-meta-field-value only fails when the field genuinely doesn't exist or the request is invalid, never because the stored value happens to be falsy.

acpt/save-meta-field-value

Input

Property	Type	Required	Description
(location)		Yes	Exactly one of the location properties above
box_name	string	Yes
field_name	string	Yes
value	any	Yes	Shape depends on the field type — a string for a Text field, an array for a Repeater, an attachment ID for an Image field, etc.
forged_by	array	No	Advanced: used when writing to a cloned field instance. Most calls can omit this.

$result = wp_get_ability('acpt/save-meta-field-value')->execute([
    'post_id'    => 12,
    'box_name'   => 'info',
    'field_name' => 'release_date',
    'value'      => '2024-11-14',
]);

For a Repeater field, value is the complete, final list of rows — this call replaces the entire stored array, it does not add to it. Sending just one row overwrites the first existing row instead of appending a new one. To add a single row without re-sending the existing ones, use acpt/append-meta-field-value below.

acpt/append-meta-field-value

Appends a single row to a Repeater field, without having to fetch and re-send the rows that are already stored.

Input

Property	Type	Required	Description
(location)		Yes	Exactly one of the location properties above
box_name	string	Yes
field_name	string	Yes	Must refer to a Repeater field — any other field type is rejected
value	object	Yes	The row to append, keyed by each child field name
forged_by	array	No	Advanced, see above

$result = wp_get_ability('acpt/append-meta-field-value')->execute([
    'post_id'    => 12,
    'box_name'   => 'info',
    'field_name' => 'subscribers',
    'value'      => [
        'user'       => 45,
        'expiration' => '2026-08-10',
    ],
]);

acpt/delete-meta-field-value

Input

Property	Type	Required	Description
(location)		Yes	Exactly one of the location properties above
box_name	string	Yes
field_name	string	Yes
forged_by	array	No	Advanced, see above

$result = wp_get_ability('acpt/delete-meta-field-value')->execute([
    'post_id'    => 12,
    'box_name'   => 'info',
    'field_name' => 'release_date',
]);