> 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/developers/functions/bulk_save_acpt_meta_field_values.md).

# bulk\_save\_acpt\_meta\_field\_values

Write or delete many field values on posts in one call (Public API, level 1)

Write (or delete) many field values in one call. ACPT validates each value with its own rules and stores it in its own format, exactly as a save from the post editor would. Part of the [Public API](https://docs.acpt.io/developers/public-api.md) (level 1, ACPT 2.1.10+).

The function never opens or commits a transaction, fires no hooks and cleans no caches. Call [`flush_acpt_caches`](https://docs.acpt.io/developers/functions/flush_acpt_caches.md) after your commit.

### Usage

```php
$result = bulk_save_acpt_meta_field_values(
    [
        ['object_type' => 'post', 'object_id' => 12, 'field_id' => $isbnFieldId,   'value' => '978-0-00-000000-0'],
        ['object_type' => 'post', 'object_id' => 12, 'field_id' => $formatFieldId, 'value' => 'paperback'],
        ['object_type' => 'post', 'object_id' => 13, 'field_id' => $isbnFieldId,   'value' => null], // delete
    ],
    ['return_previous' => true]
);

if (is_wp_error($result)) {
    // the whole call failed: nothing was written
} else {
    // $result['saved'], $result['errors'], $result['previous']
}
```

### Parameters

| Parameter | Type  | Required | Description                |
| --------- | ----- | -------- | -------------------------- |
| `rows`    | array | Required | The value rows (see below) |
| `options` | array | Optional | See options below          |

#### Rows

Each row needs all four keys:

| Key           | Type   | Description                                                                              |
| ------------- | ------ | ---------------------------------------------------------------------------------------- |
| `object_type` | string | `post` (the only type at level 1)                                                        |
| `object_id`   | int    | The post ID. Its post type must be in the field group's location rules                   |
| `field_id`    | string | The field ID                                                                             |
| `value`       | mixed  | The value, in the shape of the table below, or `null` to delete the field's stored value |

ACPT sets or deletes **every** meta key of the field (the main key and its extra keys, such as `_type` and `_id`), so no stale extra key is left behind. Only top-level fields of the 15 types below can be written.

| Field type                   | Value to send                            | Refused when                                            |
| ---------------------------- | ---------------------------------------- | ------------------------------------------------------- |
| `Text`, `Textarea`, `Editor` | string (HTML kept as is)                 | not a string                                            |
| `Number`                     | int or float                             | not an int or float                                     |
| `Email`                      | trimmed string                           | fails ACPT's email check                                |
| `Url`                        | trimmed string                           | fails ACPT's URL check                                  |
| `Select`, `Radio`            | string, one of the field's choice values | not a string, or not a choice value                     |
| `Checkbox`, `SelectMulti`    | array of strings, each a choice value    | not an array of strings, or any item not a choice value |
| `Toggle`                     | bool                                     | not a bool                                              |
| `Date`                       | `Y-m-d`                                  | not a real date in that format                          |
| `DateTime`                   | `Y-m-d H:i:s`                            | not a real date and time in that format                 |
| `Time`                       | `H:i:s`                                  | not a real time in that format                          |
| `Color`                      | lowercase `#rrggbb` or `#rrggbbaa`       | anything else                                           |

#### Options

| Option               | Type | Default        | Description                                                                 |
| -------------------- | ---- | -------------- | --------------------------------------------------------------------------- |
| `rows_per_insert`    | int  | `500`          | Rows written per `INSERT` statement. Below 1 counts as 1                    |
| `return_previous`    | bool | `false`        | Return each row's previous values in `previous`                             |
| `max_previous_bytes` | int  | `0` (no limit) | Refuse a row whose previous values together are larger than this many bytes |

Unknown options are ignored.

### Return

| Type       | Description                                   |
| ---------- | --------------------------------------------- |
| array      | `saved`, `errors` and `previous` (see below)  |
| `WP_Error` | When the whole call fails: nothing is written |

| Key        | Type  | Description                                                                                                                                                             |
| ---------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `saved`    | int   | Number of rows written                                                                                                                                                  |
| `errors`   | array | Row index → `{code, message}`, for every row that was not written                                                                                                       |
| `previous` | array | Row index → every meta key of the field → its old raw value (`null` when the key was absent). Read before anything is written. Empty unless `return_previous` is `true` |

`saved + count(errors)` always equals the number of rows. Saving `previous` back (with `null` meaning delete) restores the post.

#### Row errors

A row error never stops the other rows, and a row with an error is never written.

| Code                           | When                                                                                                                                                                                                |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `acpt_validation_failed`       | The value doesn't fit its field type or choices, the post type isn't in the field group's location rules, the row is malformed, or the row repeats an earlier row's post and field in the same call |
| `acpt_object_not_found`        | No post with that ID (any post status counts as found)                                                                                                                                              |
| `acpt_object_type_unsupported` | Any `object_type` other than `post`                                                                                                                                                                 |
| `acpt_previous_too_large`      | The row's previous values are larger than `max_previous_bytes`                                                                                                                                      |

#### Whole call errors

| Code                 | When                                                                            | Error data                   |
| -------------------- | ------------------------------------------------------------------------------- | ---------------------------- |
| `acpt_unknown_field` | A `field_id` matches no field. Checked for every row before anything is written | `field_ids`: the unknown IDs |
| `acpt_db_error`      | An unexpected database failure                                                  | none                         |

An empty `rows` array answers `['saved' => 0, 'errors' => [], 'previous' => []]`.
