diff --git a/docs/store-operations/catalog/graphql-admin/store-metafields b/docs/store-operations/catalog/graphql-admin/store-metafields
new file mode 100644
index 000000000..a3465a36b
--- /dev/null
+++ b/docs/store-operations/catalog/graphql-admin/store-metafields
@@ -0,0 +1,134 @@
+# Store metafields
+
+Store metafields allow you to attach a metafield to the store itself. They are suitable for any global information against the store that is not channel specific. Channel metafields are appropriate for any storefront-specific data you need to store in metafields. There are two ways to create a store metafield in Admin GraphQL. You can remove the resource ID or use the store’s Global ID. Examples of each type are below:
+
+## Remove resource ID
+
+
+
+ ```graphql filename="Example mutation: Create a store metafield" showLineNumbers copy
+ POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
+ X-Auth-Token: {{ACCESS_TOKEN}}
+ Content-Type: application/json
+ Accept: application/json
+
+ mutation Metafield($input: CreateMetafieldInput!) {
+ metafield {
+ createMetafield(input: $input) {
+ metafield {
+ id
+ description
+ key
+ namespace
+ permissionSet
+ resourceId
+ value
+ ownerClientId
+ }
+ }
+ }
+}
+```
+```json filename="GraphQL variables" showLineNumbers copy
+ {
+ "input":{
+ "namespace": "Warehouse Locations",
+ "key": "Location",
+ "value": "4HG",
+ "permissionSet": "APP_ONLY"
+ }
+}
+ ```
+
+
+
+ ```json filename="Example mutation: Create a store metafield" showLineNumbers copy
+ {
+ "data": {
+ "metafield": {
+ "createMetafield": {
+ "metafield": {
+ "id": "bc/store/metafield/74",
+ "description": "",
+ "key": "'Location",
+ "namespace": Warehouse Locations",
+ "permissionSet": "APP_ONLY",
+ "resourceId": "bc/store/store/1001197568",
+ "value": "4HG",
+ "ownerClientId": "k8l7zz0ynkd1bfbxx02p2k7pnk3n8ov"
+ }
+ }
+ }
+ }
+}
+```
+
+
+
+## Use the Global ID
+
+
+
+ ```graphql filename="Example mutation: Create a store metafield" showLineNumbers copy
+ POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/graphql
+ X-Auth-Token: {{ACCESS_TOKEN}}
+ Content-Type: application/json
+ Accept: application/json
+
+ mutation Metafield($input: CreateMetafieldInput!) {
+ metafield {
+ createMetafield(input: $input) {
+ metafield {
+ id
+ description
+ key
+ namespace
+ permissionSet
+ resourceId
+ value
+ ownerClientId
+ }
+ }
+ }
+}
+```
+```json filename="GraphQL variables" showLineNumbers copy
+ {
+ "input":{
+ "namespace": "Warehouse Locations",
+ "key": "Location",
+ "value": "4HG",
+ "permissionSet": "APP_ONLY",
+ "resourceId": "bc/store/store/1001197568"
+ }
+}
+ ```
+
+
+
+ ```json filename="Example mutation: Create a store metafield" showLineNumbers copy
+ {
+ "data": {
+ "metafield": {
+ "createMetafield": {
+ "metafield": {
+ "id": "bc/store/metafield/71",
+ "description": "",
+ "key": "'Location",
+ "namespace": Warehouse Locations",
+ "permissionSet": "APP_ONLY",
+ "resourceId": "bc/store/store/1001197568",
+ "value": "4HG",
+ "ownerClientId": "k8l7zz0ynkd1bfbxx02p2k7pnk3n8ov"
+ }
+ }
+ }
+ }
+}
+```
+
+
+
+
+You can create 10,000 metafields instead of the typical limit of 250 per entity-per-client-id.
+
diff --git a/reference/store_metafields.v3.yml b/reference/store_metafields.v3.yml
new file mode 100644
index 000000000..a70e7eef4
--- /dev/null
+++ b/reference/store_metafields.v3.yml
@@ -0,0 +1,733 @@
+openapi: 3.0.0
+info:
+ title: Store Metafields REST API
+ version: 1.0.0
+ description: This API can be used to create store metafields.
+ termsOfService: 'https://www.bigcommerce.com/terms'
+ contact:
+ name: BigCommerce
+ url: 'https://www.bigcommerce.com'
+ email: support@bigcommerce.com
+servers:
+ - url: 'https://api.bigcommerce.com/stores/{store_hash}/v3'
+ variables:
+ store_hash:
+ default: store_hash
+ description: Permanent ID of the BigCommerce store.
+tags:
+ - name: Batch metafields
+security:
+ - authToken: []
+paths:
+ '/store/metafields':
+ get:
+ description: Get all store metafield
+ summary: Get all store metafields
+ tags:
+ - Batch metafields
+ operationId: getStoreMetafields
+ parameters:
+ - $ref: '#/components/parameters/PageParam'
+ - $ref: '#/components/parameters/LimitParam'
+ - $ref: '#/components/parameters/MetafieldKeyParam'
+ - $ref: '#/components/parameters/MetafieldKeyInParam'
+ - $ref: '#/components/parameters/MetafieldNamespaceParam'
+ - $ref: '#/components/parameters/MetafieldNamespaceInParam'
+ - $ref: '#/components/parameters/DirectionParam'
+ - $ref: '#/components/parameters/IncludeFieldsParamMetafields'
+ - $ref: '#/components/parameters/date_modified_min'
+ - $ref: '#/components/parameters/date_modified_max'
+ - $ref: '#/components/parameters/date_created_min'
+ - $ref: '#/components/parameters/date_created_max'
+ responses:
+ '200':
+ description: |
+ List of `Metafield` objects.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MetaFieldCollectionResponse_Batch'
+ post:
+ summary: Create multiple metafields
+ tags:
+ - Batch metafields
+ description: Create multiple store metafields
+ operationId: createStoreMetafields
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ allOf:
+ - $ref: '#/components/schemas/MetafieldBase_Post'
+ - type: object
+ properties:
+ resource_id:
+ type: string
+ example: "42"
+ description: |
+ The store ID with which the metafield is associated.
+ required:
+ - resource_id
+ responses:
+ '200':
+ description: Metafields created successfully
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MetaFieldCollectionResponse_Batch_POST_PUT'
+ '400':
+ description: Bad Request. Input is invalid.
+ content:
+ application/json:
+ schema:
+ description: ''
+ type: object
+ properties:
+ status:
+ type: number
+ title:
+ type: string
+ minLength: 1
+ type:
+ type: string
+ minLength: 1
+ detail:
+ type: string
+ minLength: 1
+ example:
+ status: 400
+ title: Input is invalid
+ type: 'https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes'
+ detail: Syntax error
+ '422':
+ description: |
+ Response object for metafields creation with partial success.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT'
+ put:
+ summary: Update multiple metafields
+ tags:
+ - Batch metafields
+ operationId: UpdateStoreMetafields
+ description: Update multiple metafields
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ allOf:
+ - $ref: '#/components/schemas/MetafieldBase_Post'
+ - type: object
+ properties:
+ id:
+ type: string
+ example: "42"
+ description: |
+ The ID of metafield to update.
+ required:
+ - id
+ description: ""
+ responses:
+ '200':
+ description: Metafields updated successfully
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MetaFieldCollectionResponse_Batch_POST_PUT'
+ '400':
+ description: Bad Request. Input is invalid.
+ content:
+ application/json:
+ schema:
+ description: ''
+ type: object
+ properties:
+ status:
+ type: number
+ title:
+ type: string
+ minLength: 1
+ type:
+ type: string
+ minLength: 1
+ detail:
+ type: string
+ minLength: 1
+ example:
+ status: 400
+ title: Input is invalid
+ type: 'https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes'
+ detail: Syntax error
+ '422':
+ description: |
+ Response object for metafields creation with partial success.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_POST_PUT'
+ delete:
+ summary: Delete multiple metafields
+ tags:
+ - Batch metafields
+ operationId: DeleteStoreMetafields
+ description: Delete all store metafields
+ requestBody:
+ content:
+ application/json:
+ schema:
+ type: array
+ items:
+ type: integer
+ description: List of metafield `id`s.
+ responses:
+ '200':
+ description: Metafields deleted successfully
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MetaFieldCollectionDeleteResponseSuccess'
+ '400':
+ description: Bad Request. Input is invalid.
+ content:
+ application/json:
+ schema:
+ description: ''
+ type: object
+ properties:
+ status:
+ type: number
+ title:
+ type: string
+ minLength: 1
+ type:
+ type: string
+ minLength: 1
+ detail:
+ type: string
+ minLength: 1
+ example:
+ status: 400
+ title: Input is invalid
+ type: 'https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes'
+ detail: Syntax error
+ '422':
+ description: |
+ Response object for metafields deletion with partial success.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MetaFieldCollectionResponsePartialSuccess_DELETE'
+components:
+ securitySchemes:
+ authToken:
+ type: apiKey
+ in: header
+ name: X-Auth-Token
+ parameters:
+ Accept:
+ name: Accept
+ in: header
+ required: true
+ description: 'The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body.'
+ schema:
+ type: string
+ default: 'application/json'
+ ContentType:
+ name: Content-Type
+ in: header
+ required: true
+ schema:
+ type: string
+ default: application/json
+ PageParam:
+ name: page
+ description: |
+ Specifies the page number in a limited (paginated) list of products.
+ required: false
+ in: query
+ schema:
+ type: integer
+ date_created_min:
+ name: 'date_created:min'
+ description: |
+ 'Query parameter that lets you filter by the minimum date created, for example, `2024-05-14T09:34:00` or `2024-05-14`. Returns metafields created after this date.'
+ required: false
+ in: query
+ schema:
+ type: string
+ date_created_max:
+ name: 'date_created:max'
+ description: |
+ 'Query parameter that lets you filter by the maximum date created, for example, `2024-05-14T09:34:00` or `2024-05-14`. Returns metafields created before this date.'
+ required: false
+ in: query
+ schema:
+ type: string
+ date_modified_max:
+ name: 'date_modified:max'
+ description: |
+ 'Query parameter that lets you filter by the maximum date modified created, for example, `2024-05-14T09:34:00` or `2024-05-14`. Returns metafields modified before this date.'
+ required: false
+ in: query
+ schema:
+ type: string
+ date_modified_min:
+ name: 'date_modified:min'
+ description: |
+ 'Query parameter that lets you filter by the minimum date modified created, for example, `2024-05-14T09:34:00` or `2024-05-14`. Returns metafields modified after this date.'
+ required: false
+ in: query
+ schema:
+ type: string
+ DirectionParam:
+ name: direction
+ description: |
+ Sort direction. Acceptable values are: `asc`, `desc`.
+ required: false
+ in: query
+ schema:
+ type: string
+ enum:
+ - asc
+ - desc
+ MetafieldKeyParam:
+ name: key
+ in: query
+ description: Filter based on a metafieldʼs key.
+ required: false
+ schema:
+ type: string
+ MetafieldKeyInParam:
+ name: key:in
+ in: query
+ description: Filter based on comma-separated metafieldʼs keys. Could be used with vanilla `key` query parameter.
+ required: false
+ style: form
+ explode: false
+ schema:
+ type: array
+ items:
+ type: string
+ MetafieldNamespaceParam:
+ name: namespace
+ in: query
+ description: Filter based on a metafieldʼs namespaces.
+ required: false
+ schema:
+ type: string
+ MetafieldNamespaceInParam:
+ name: namespace:in
+ in: query
+ description: Filter based on comma-separated metafieldʼs namespaces. Could be used with vanilla `namespace` query parameter
+ required: false
+ style: form
+ explode: false
+ schema:
+ type: array
+ items:
+ type: string
+ IncludeFieldsParamMetafields:
+ name: include_fields
+ in: query
+ description: Fields to include, in a comma-separated list. The ID and the specified fields will be returned.
+ style: form
+ explode: false
+ schema:
+ type: array
+ items:
+ type: string
+ enum:
+ - resource_id
+ - key
+ - value
+ - namespace
+ - permission_set
+ - resource_type
+ - description
+ - owner_client_id
+ - date_created
+ - date_modified
+ LimitParam:
+ name: limit
+ description: |
+ Controls the number of items per page in a limited (paginated) list of products.
+ required: false
+ in: query
+ schema:
+ type: integer
+ schemas:
+ CollectionMeta:
+ type: object
+ description: Data about the response, including pagination and collection totals.
+ properties:
+ pagination:
+ type: object
+ description: Data about the response, including pagination and collection totals.
+ title: Pagination
+ properties:
+ total:
+ type: integer
+ description: |
+ Total number of items in the result set.
+ example: 36
+ count:
+ type: integer
+ description: |
+ Total number of items in the collection response.
+ example: 36
+ per_page:
+ type: integer
+ description: |
+ The amount of items returned in the collection per page, controlled by the limit parameter.
+ example: 50
+ current_page:
+ type: integer
+ description: |
+ The page you are currently on within the collection.
+ example: 1
+ total_pages:
+ type: integer
+ description: |
+ The total number of pages in the collection.
+ example: 1
+ links:
+ type: object
+ description: |
+ Pagination links for the previous and next parts of the whole collection.
+ properties:
+ previous:
+ type: string
+ description: |
+ Link to the previous page returned in the response.
+ current:
+ type: string
+ description: |
+ Link to the current page returned in the response.
+ example: '?page=1&limit=50'
+ next:
+ type: string
+ description: |
+ Link to the next page returned in the response.
+ additionalProperties: true
+ title: Collection Meta
+ x-internal: false
+ MetaFieldCollectionResponse_Batch:
+ type: object
+ description: |
+ Response payload for the BigCommerce API.
+ properties:
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Metafield'
+ meta:
+ $ref: '#/components/schemas/CollectionMeta'
+ MetaFieldCollectionResponse_Batch_POST_PUT:
+ type: object
+ description: |
+ Response payload for the BigCommerce API.
+ properties:
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Metafield'
+ errors:
+ type: array
+ items: {}
+ description: Empty for 200 responses.
+ example: []
+ meta:
+ $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta'
+ MetaFieldCollectionResponsePartialSuccess_POST_PUT:
+ type: object
+ description: |
+ Response payload for the BigCommerce API.
+ properties:
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/Metafield'
+ errors:
+ type: array
+ items:
+ $ref: '#/components/schemas/Error'
+ meta:
+ $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta'
+ MetaFieldCollectionDeleteResponseSuccess:
+ type: object
+ description: |
+ Response payload for the BigCommerce API.
+ properties:
+ data:
+ type: array
+ items:
+ type: integer
+ description: |
+ The unique identifier for the metafield.
+ example:
+ - 123
+ - 124
+ - 125
+ errors:
+ type: array
+ items: {}
+ description: Empty for 200 responses.
+ example: []
+ meta:
+ $ref: '#/components/schemas/WriteCollectionSuccessMeta'
+ x-internal: false
+ MetaFieldCollectionResponsePartialSuccess_DELETE:
+ type: object
+ description: |
+ Response payload for the BigCommerce API.
+ properties:
+ data:
+ type: array
+ items:
+ type: integer
+ description: |
+ The unique identifier for the metafield.
+ example:
+ - 123
+ errors:
+ type: array
+ items:
+ $ref: '#/components/schemas/Error'
+ meta:
+ $ref: '#/components/schemas/WriteCollectionPartialSuccessMeta'
+ x-internal: false
+ Metafield:
+ description: |
+ Allows app partners to write custom data to various resources in the API.
+ allOf:
+ - $ref: '#/components/schemas/MetafieldBase'
+ - type: object
+ properties:
+ id:
+ type: string
+ description: The unique identifier for the metafield.
+ date_created:
+ type: string
+ format: date-time
+ description: Date and time of the metafieldʼs creation.
+ example: '2022-06-16T18:39:00+00:00'
+ date_modified:
+ type: string
+ format: date-time
+ description: Date and time when the metafield was last updated.
+ example: '2022-06-16T18:39:00+00:00'
+ owner_client_id:
+ type: string
+ description: Client ID for the metafieldʼs creator.
+ example: asdfasdfasdfasdfasdfasdfasdf
+ readOnly: true
+ x-internal: false
+ MetafieldBase:
+ type: object
+ description: |
+ Common Metafield properties.
+ x-internal: false
+ properties:
+ permission_set:
+ type: string
+ description: |
+ Determines the visibility and writeability of the field by other API consumers.
+ | Value | Description |
+ | :--- | :--- |
+ | `app_only` | Private to the app that owns the field. |
+ | `read` | Visible to other API consumers. |
+ | `write` | Open for reading and writing by other API consumers. |
+ | `read_and_sf_access` | Visible to other API consumers, including on the storefront. |
+ | `write_and_sf_access` | Open for reading and writing by other API consumers, including on the storefront. |
+ enum:
+ - app_only
+ - read
+ - write
+ - read_and_sf_access
+ - write_and_sf_access
+ namespace:
+ type: string
+ description: |
+ Namespace for the metafield, for organizational purposes.
+ example: Sales Department
+ minLength: 1
+ maxLength: 64
+ key:
+ type: string
+ description: |
+ The name of the field, for example: `location_id`, `color`.
+ minLength: 1
+ maxLength: 64
+ example: Staff Name
+ value:
+ type: string
+ description: |
+ The value of the field, for example: `1`, `blue`.
+ minLength: 1
+ maxLength: 65535
+ example: Ronaldo
+ description:
+ type: string
+ description: |
+ Description for the metafields.
+ example: order
+ minLength: 0
+ maxLength: 255
+ resource_type:
+ type: string
+ description: |
+ The type of resource with which the metafield is associated.
+ enum:
+ - brand
+ - product
+ - variant
+ - category
+ - cart
+ example: cart
+ resource_id:
+ type: string
+ description: |
+ The unique identifier for the resource with which the metafield is associated.
+ example: '0'
+ readOnly: true
+ MetafieldBase_Post:
+ type: object
+ description: |
+ Common Metafield properties.
+ x-internal: false
+ properties:
+ permission_set:
+ type: string
+ description: |
+ Determines the visibility and writeability of the field by other API consumers.
+
+ |Value|Description |
+ |:-|:-|
+ |`app_only`|Private to the app that owns the field|
+ |`read`|Visible to other API consumers|
+ |`write`|Open for reading and writing by other API consumers|
+ |`read_and_sf_access`|Visible to other API consumers, including on storefront|
+ |`write_and_sf_access`|Open for reading and writing by other API consumers, including on storefront|
+ enum:
+ - app_only
+ - read
+ - write
+ - read_and_sf_access
+ - write_and_sf_access
+ namespace:
+ type: string
+ description: |
+ Namespace for the metafield, for organizational purposes.
+ example: Sales Department
+ minLength: 1
+ maxLength: 64
+ key:
+ type: string
+ description: |
+ The name of the field, for example: `location_id`, `color`.
+ minLength: 1
+ maxLength: 64
+ example: Staff Name
+ value:
+ type: string
+ description: |
+ The value of the field, for example: `1`, `blue`.
+ minLength: 1
+ maxLength: 65535
+ example: Bob
+ description:
+ type: string
+ description: |
+ Description for the metafields.
+ minLength: 0
+ maxLength: 255
+ example: Name of Staff Member
+ required:
+ - permission_set
+ - namespace
+ - key
+ - value
+ example:
+ permission_set: app_only
+ namespace: Sales Department
+ key: Status
+ value: upcoming
+ description: Company sales
+ WriteCollectionPartialSuccessMeta:
+ type: object
+ description: Additional data about the response.
+ properties:
+ total:
+ type: integer
+ description: |
+ Total number of items in the result set.
+ example: 3
+ success:
+ type: integer
+ description: |
+ Total number of items that were successfully deleted.
+ example: 1
+ failed:
+ type: integer
+ description: |
+ Total number of items that failed to be deleted.
+ example: 2
+ title: Collection Meta
+ x-internal: false
+ WriteCollectionSuccessMeta:
+ type: object
+ description: Additional data about the response.
+ properties:
+ total:
+ type: integer
+ description: |
+ Total number of items in the result set.
+ example: 3
+ success:
+ type: integer
+ description: |
+ Total number of items that were successfully deleted.
+ example: 3
+ failed:
+ type: integer
+ description: |
+ Total number of items that failed to be deleted.
+ example: 0
+ title: Collection Meta
+ x-internal: false
+ Error:
+ type: object
+ description: |
+ Error response payload for the BigCommerce API.
+ properties:
+ status:
+ type: integer
+ description: |
+ The HTTP status code for the error.
+ example: 422
+ title:
+ type: string
+ description: |
+ The error title.
+ example: Bulk operation has failed
+ type:
+ type: string
+ description: |
+ The error type.
+ example: https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes
+ errors:
+ $ref: '#/components/schemas/ErrorDetail'
+ ErrorDetail:
+ type: object
+ properties: {}
+ additionalProperties: true
+ description: |
+ Error detail response payload for the BigCommerce API.
+ example:
+ "1": "Unauthorized to delete"
+ "2": "Metafield does not exist"