> 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/save_acpt_meta_group.md).

# save\_acpt\_meta\_group

Create or update a field group

Create or update a field group, including its boxes and fields.

Performs an upsert: if a group with the given `name` already exists (and no `id` is passed), its existing state is merged with the ones you provide — a partial update (e.g. `belongs` only) doesn't wipe `boxes`/fields you didn't resend.

### Usage

```php
save_acpt_meta_group([
    'name'    => 'new-group',
    'label'   => 'New group',
    'display' => 'horizontalTabs',
    'belongs' => [
        [
            'belongsTo' => 'customPostType',
            'operator'  => '=',
            'find'      => 'page',
        ],
    ],
    'boxes' => [
        [
            'name'   => 'box',
            'label'  => 'Box',
            'fields' => [
                [
                    'name'  => 'field',
                    'label' => 'Field',
                    'type'  => 'Text',
                ],
            ],
        ],
    ],
]);
```

To rename an existing group, include `new_name`:

```php
save_acpt_meta_group([
    'name'     => 'new-group',
    'new_name' => 'new-group-modified',
]);
```

### Parameters

| Parameter  | Type   | Required | Description                                                                                        |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `name`     | string | Required | The group name (slug)                                                                              |
| `id`       | string | Optional | Group UUID — if provided, updates the existing group instead of resolving it by `name`             |
| `new_name` | string | Optional | The new group name when renaming an existing group                                                 |
| `label`    | string | Optional | The human-readable group label                                                                     |
| `display`  | string | Optional | How to render the group. Allowed values: `standard`, `accordion`, `verticalTabs`, `horizontalTabs` |
| `belongs`  | array  | Optional | Location rules controlling which WordPress context displays this group — see below                 |
| `boxes`    | array  | Optional | The group's meta boxes, each containing its own fields — see below                                 |

#### `belongs` rule fields

| Field       | Type   | Description                                                                                                                                                               |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `belongsTo` | string | One of `PARENT_POST_ID`, `POST_ID`, `POST_CAT`, `POST_TAX`, `POST_TEMPLATE`, `TERM_ID`, `USER_ID`, `comment`, `customPostType`, `taxonomy`, `media`, `optionPage`, `user` |
| `operator`  | string | One of `=`, `!=`, `<`, `>`, `<=`, `>=`, `LIKE`, `NOT_LIKE`, `IN`, `NOT_IN`, `NULL`, `NOT_NULL`, `BLANK`, `NOT_BLANK`, `CHECKED`, `NOT_CHECKED`                            |
| `find`      | string | The target value (e.g. a post type slug) — not needed for every `operator`                                                                                                |
| `logic`     | string | `AND` or `OR`, when combined with other rules                                                                                                                             |

#### `boxes[]` fields

| Field    | Type   | Description                                                                                                                                                                                                                                                           |
| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`   | string | Required. The box name (slug)                                                                                                                                                                                                                                         |
| `label`  | string | The human-readable box label                                                                                                                                                                                                                                          |
| `fields` | array  | The box's fields — see [`save_acpt_meta_field`](/developers/functions/save_acpt_meta_field.md) for the full field object structure (`name`, `type`, `options`, `advancedOptions`, `validationRules`, `visibilityConditions`, `relations`, `children`, `blocks`, etc.) |

{% hint style="info" %}
For adding, updating, or removing a single box or field without resending the whole group, prefer [`save_acpt_meta_box`](/developers/functions/save_acpt_meta_box.md) / [`save_acpt_meta_field`](/developers/functions/save_acpt_meta_field.md) — they handle the merge-with-existing-state logic for you.
{% endhint %}

### Return

| Type   | Description                           |
| ------ | ------------------------------------- |
| `bool` | `true` on success, `false` on failure |