Metafields
The typed fields a shop and its apps keep on records.
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 |
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 |
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 |
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.jsonDelete 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. |
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. |
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. |
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