> For the complete documentation index, see [llms.txt](https://docs.acpt.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acpt.io/integrations/abilities-api/field-values.md).

# 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      |

{% hint style="warning" %}
These abilities are thin wrappers over ACPT's [`get_acpt_fields()`](/developers/functions/get_acpt_fields.md) / [`get_acpt_field()`](/developers/functions/get_acpt_field.md) / [`save_acpt_meta_field_value()`](/developers/functions/save_acpt_meta_field_value.md) / [`append_acpt_meta_field_value()`](/developers/functions/append_acpt_meta_field_value.md) / [`delete_acpt_meta_field_value()`](/developers/functions/delete_acpt_meta_field_value.md) 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.
{% endhint %}

## 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`                                                           |

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

```json
{
  "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`                 |

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

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

{% hint style="info" %}
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.
{% endhint %}

## 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.                                           |

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

{% hint style="warning" %}
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.
{% endhint %}

## 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                                               |

```php
$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                          |

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