> 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_definition.md).

# save\_acpt\_meta\_group\_definition

Create a field group with its boxes and fields, under exactly the names sent (Public API, level 1)

Create **one** field group with its boxes and fields, under exactly the names you send, and get back the new IDs keyed by those names. Part of the [Public API](https://docs.acpt.io/developers/public-api.md) (level 1, ACPT 2.1.10+).

Unlike [`save_acpt_meta_group`](https://docs.acpt.io/developers/functions/save_acpt_meta_group.md), this function **never merges** into an existing group, never renames anything, and never opens or commits a database transaction. Check the name first with [`acpt_meta_group_exists`](https://docs.acpt.io/developers/functions/acpt_meta_group_exists.md).

### Usage

```php
$result = save_acpt_meta_group_definition([
    'name'       => 'book_details',
    'label'      => 'Book details',
    'belongs_to' => [['post_type' => 'book']],
    'boxes'      => [
        [
            'name'   => 'book_box',
            'label'  => 'Book',
            'fields' => [
                ['name' => 'isbn', 'label' => 'ISBN', 'type' => 'Text'],
                ['name' => 'format', 'label' => 'Format', 'type' => 'Select', 'choices' => [
                    ['value' => 'hardcover', 'label' => 'Hardcover'],
                    ['value' => 'paperback', 'label' => 'Paperback'],
                ]],
            ],
        ],
    ],
]);

if (is_wp_error($result)) {
    // $result->get_error_code(), $result->get_error_data()
} else {
    $isbnFieldId = $result['boxes']['book_box']['fields']['isbn'];
}
```

### Parameters

| Parameter    | Type  | Required | Description                      |
| ------------ | ----- | -------- | -------------------------------- |
| `definition` | array | Required | The group definition (see below) |

#### The definition

| Key                    | Type                                      | Required                                                            | Rule                                                                                                                                                       |
| ---------------------- | ----------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                 | string                                    | Required                                                            | `^[a-z0-9_-]{1,64}$`, unique among field groups (case sensitive)                                                                                           |
| `label`                | string                                    | Required                                                            | Trimmed, then 1 to 255 characters                                                                                                                          |
| `belongs_to`           | array of `{post_type: string}`            | Required, at least one                                              | Level 1 supports post types only; each must be registered; repeats are ignored                                                                             |
| `boxes`                | array of boxes                            | Required, at least one                                              | Box names unique within the group                                                                                                                          |
| box `name` / `label`   | string                                    | Required                                                            | Same rules as the group `name` / `label`                                                                                                                   |
| box `fields`           | array of fields                           | Required, at least one                                              | Field names unique **across the whole group** (meta keys are built from box and field names)                                                               |
| field `name` / `label` | string                                    | Required                                                            | Same rules as the group `name` / `label`                                                                                                                   |
| field `type`           | string                                    | Required                                                            | One of `Checkbox`, `Color`, `Date`, `DateTime`, `Editor`, `Email`, `Number`, `Radio`, `Select`, `SelectMulti`, `Text`, `Textarea`, `Time`, `Toggle`, `Url` |
| field `choices`        | array of `{value: string, label: string}` | For `Checkbox`, `Radio`, `Select`, `SelectMulti`; ignored otherwise | At least one; `value` unique within the field; value and label at most 255 characters                                                                      |

The group is saved like one created from the editor: standard display, one `=` location rule per post type, boxes in the main column.

### Return

| Type       | Description                                                                                                |
| ---------- | ---------------------------------------------------------------------------------------------------------- |
| array      | `group_id`, and `boxes` keyed by box name, each with its `box_id` and its `fields` (field name → field ID) |
| `WP_Error` | When the definition is refused or the save fails (see below)                                               |

```php
[
    'group_id' => '9c1d…',
    'boxes'    => [
        'book_box' => [
            'box_id' => '41fa…',
            'fields' => [
                'isbn'   => 'b2e0…',
                'format' => '77c3…',
            ],
        ],
    ],
]
```

#### Errors

The whole definition is validated first, then the names are checked against what's stored. Nothing is written in any of these cases.

| Code                      | When                                     | Error data                                                                                                                          |
| ------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `acpt_invalid_definition` | The first broken rule, in document order | `path`: the offending key, e.g. `name`, `boxes[0].fields[2].name`, `belongs_to[0].post_type`, `boxes[1].fields[0].choices[3].value` |
| `acpt_group_name_taken`   | A field group with this name exists      | `name`                                                                                                                              |
| `acpt_box_name_taken`     | Two boxes have the same name             | `name`                                                                                                                              |
| `acpt_db_error`           | An unexpected database failure           | none                                                                                                                                |

{% hint style="warning" %}
After any `WP_Error`, roll back your transaction: the function promises no clean state for a write that failed partway.
{% endhint %}
