# Metafields

> The typed fields a shop and its apps keep on records.

Source: https://storeware.ai/docs/api-reference/rest/metafields

## List metafield definitions

`GET /api/v1/stores/{storeId}/metafield-definitions`

Every field the shop records, by kind of record and then position, the shop’s own and those its apps declare.

Needs `stores:read`.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `storeId` | path | string | The shop. |
| `ownerType` | query | string | Only the fields for this kind of record. Any other value is a 400. One of `product`, `variant`, `collection`, `customer`, `order`, `store`. |

**Answers** `200`

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of [MetafieldDefinition](https://storeware.ai/docs/api-reference/rest/objects#metafielddefinition) |  |

```bash
curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/metafield-definitions" \
  -H "Authorization: Bearer $TOKEN"
```

## Get a metafield definition

`GET /api/v1/stores/{storeId}/metafield-definitions/{definitionId}`

Needs `stores:read`.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `storeId` | path | string | The shop. |
| `definitionId` | path | string | The definition. |

**Answers** `200`

| Field | Type | Description |
| --- | --- | --- |
| `data` | [MetafieldDefinition](https://storeware.ai/docs/api-reference/rest/objects#metafielddefinition) |  |

```bash
curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/metafield-definitions/$DEFINITION_ID" \
  -H "Authorization: Bearer $TOKEN"
```

## Update a metafield definition

`PATCH /api/v1/stores/{storeId}/metafield-definitions/{definitionId}`

Changes only the fields sent. The namespace, key, type and list flag cannot change. An app may change only the fields its manifest declared; any other answers 403 `metafield_definition_not_yours`.

Needs `stores:write`.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `storeId` | path | string | The shop. |
| `definitionId` | path | string | The definition. |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | 1 to 200 characters. |
| `description` | string or null | No | Up to 2,000 characters. |
| `validations` | object | No | Default `{}`. |
| `validations.min` | number | No |  |
| `validations.max` | number | No |  |
| `validations.minLength` | integer | No | At least 0. |
| `validations.maxLength` | integer | No | At least 1. |
| `validations.choices` | array of string | No | Up to 100 items. |
| `validations.scale` | integer | No | From 0 to 8. |
| `storefrontVisible` | boolean | No |  |
| `searchFacet` | boolean | No |  |
| `position` | integer | No | At least 0. |

**Answers** `200`

| Field | Type | Description |
| --- | --- | --- |
| `data` | [MetafieldDefinition](https://storeware.ai/docs/api-reference/rest/objects#metafielddefinition) |  |

```bash
curl -X PATCH "https://api.storeware.ai/api/v1/stores/$STORE_ID/metafield-definitions/$DEFINITION_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
```

## Delete a metafield definition

`DELETE /api/v1/stores/{storeId}/metafield-definitions/{definitionId}`

Refused while any record holds a value for it, unless `withValues=1` is sent, which deletes every value with it. An app may delete only the fields its manifest declared; any other answers 403 `metafield_definition_not_yours`.

Needs `stores:write`.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `storeId` | path | string | The shop. |
| `definitionId` | path | string | The definition. |
| `withValues` | query | string | `1` deletes the field’s values too. One of `1`. |

**Answers** `200`

| Field | Type | Description |
| --- | --- | --- |
| `data` | object |  |
| `data.deletedValues` | integer | How many values went with it. |

```bash
curl -X DELETE "https://api.storeware.ai/api/v1/stores/$STORE_ID/metafield-definitions/$DEFINITION_ID" \
  -H "Authorization: Bearer $TOKEN"
```

## List the shop’s metafields

`GET /api/v1/stores/{storeId}/metafields`

Every metafield value set on the shop, each with its definition.

Needs `stores:read`.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `storeId` | path | string | The shop. |

**Answers** `200`

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].definitionId` | string (uuid) |  |
| `data[].namespace` | string |  |
| `data[].key` | string |  |
| `data[].label` | string | The merchant’s name for the field. |
| `data[].type` | string | single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types. |
| `data[].isList` | boolean |  |
| `data[].storefrontVisible` | boolean |  |
| `data[].searchFacet` | boolean |  |
| `data[].position` | integer |  |
| `data[].value` | any | The value, or a list of values when `isList`. |
| `data[].displayValue` | string | The value as one line of text, lists joined. |
| `data[].source` | string | Who set it: the merchant, an import, or an app’s slug. |

```bash
curl "https://api.storeware.ai/api/v1/stores/$STORE_ID/metafields" \
  -H "Authorization: Bearer $TOKEN"
```

## Set the shop’s metafields

`PUT /api/v1/stores/{storeId}/metafields`

Sets up to 25 values in one call. A null value clears its field; keys not named are left alone. An app may set only the fields its manifest declares.

Needs `stores:write`.

**Parameters**

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `storeId` | path | string | The shop. |

**Body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `metafields` | array of object | Yes | Up to 25 items. At least 1 item. |
| `metafields[].namespace` | string | No | Default `custom`. |
| `metafields[].key` | string | Yes |  |
| `metafields[].value` | any | No |  |

**Answers** `200`

| Field | Type | Description |
| --- | --- | --- |
| `data` | array of object |  |
| `data[].definitionId` | string (uuid) |  |
| `data[].namespace` | string |  |
| `data[].key` | string |  |
| `data[].label` | string | The merchant’s name for the field. |
| `data[].type` | string | single_line_text, multi_line_text, integer, decimal, boolean, date, url and the other definition types. |
| `data[].isList` | boolean |  |
| `data[].storefrontVisible` | boolean |  |
| `data[].searchFacet` | boolean |  |
| `data[].position` | integer |  |
| `data[].value` | any | The value, or a list of values when `isList`. |
| `data[].displayValue` | string | The value as one line of text, lists joined. |
| `data[].source` | string | Who set it: the merchant, an import, or an app’s slug. |

```bash
curl -X PUT "https://api.storeware.ai/api/v1/stores/$STORE_ID/metafields" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @body.json
```