Overview​

Metafields are a way to add extended information to SHOPLINE resources (such as products, blogs, orders, etc.) as data extensions. Metafields can be used to create and display additional variables for SHOPLINE stores, as well as store specific information (e.g., specifications, size charts, downloadable documents, release dates, images, or part numbers) to customize store functionality or style. Merchants and app developers can query and edit the metadata stored in metafields from the SHOPLINE Merchant Admin or the Metafields OpenAPI. Additionally, you can use HandleBar to access metafields in themes.

Components of Metafields​

• Owner Resource: The resource type to which the metafield belongs, also known as "Owner Resource Type". For example, products, custom pages, etc.
• Owner ID: The ID of the owner resource to which the metafield belongs. For example, the ID of product A: 1605898661.
• Namespace: A container for a group of metafields. Using namespaces to group metafields prevents conflicts between merchant's metafields and other metafields with the same key name.
• Key: The key value of the metafield.
• Type: The data type in which the metafield's data is stored, such as single-line text, URL, integer, etc.
• Value: The data to be stored in the metafield. Regardless of the data type of the metafield, the value is always stored as a string.
• Name: The name of the metafield.
• Description: A descriptive information defining the metafield.

Metafield Resource Types​

Based on the hierarchical level of Metafields resource object types in the store, there are three resource levels: store-level, first-level under the store, and second-level under the store. Each level includes the following owner resource types:

• Store-level:

Resources directly belonging to the store (e.g., shop). You can perform operations such as paged query, detail query, total count query, addition, update, and delete for metafields directly belonging to the store (OwnerResource not required).

• First-level under the store:

Sub-resources under the store, such as orders, products, customers, collections, blogs, articles, customers, pages, locations. You can perform operations such as paged query, detail query, total count query, addition, update, and delete for metafields under these resources (OwnerResource required).

• Second-level under the store:

Resources one level further under the first-level resources, such as variants. You can perform operations such as paged query, detail query, total count query, addition, update, and delete for metafields under these resources. (You need to provide both the owner resource type from the previous level (p_resource) and the current level resource type (resource)).

Data Types (Type)​

Common Data Types​

Each Metafield and Metafield definition has a type that defines the data type it can store. Currently, SHOPLINE Metafields and Metafield definitions can have the following data types as shown in the table below:

Reference Data Types​

Reference Metafields allow you to store references to SHOPLINE resources.

List data types​

List metafields allow you to store multiple values in a single metafield.

The maximum number of values that can be stored in a metafield list is 128. This value must be provided as a JSON array.

Note：Currently, SHOPLINE themes (and HandleBars) do not support list data types. However, OpenAPI and SHOPLINE admin supports the following list types:

Managing metafield definitions​

Defined metafields​

If you need to categorize and manage metafields with the same OwnerResource, Namespace, Key, and Type, you can use the defined metafields related interfaces to perform operations:

• Create Metafield Definition
• Update Metafield Definition
• Delete Metafield Definition
• Query Metafield Definition

Additionally, you can perform these operations in the merchant admin panel: [Settings] -> [Metafields] -> Select OwnerResource

Metafield definitions are provided to differentiate between operations in the merchant admin panel (Admin) and those performed by the app (APP) for access permissions isolation.

Setting access permission to empty​

When users create metafield definitions in the merchant admin panel or via OpenAPI without setting the access field, and the Namespace does not require an APP identifier, the created metafield definitions can be modified by both the merchant (for updating, deleting, and querying metafields definitions) and any app (for updating, deleting, and querying metafields definitions).

Passing access permission value​

When defining access in the admin field under the access in the interface, pass the permission value, such as MERCHANT_READ_WRITE, MERCHANT_READ, PRIVATE.

1. MERCHANT_READ_WRITE：The store is writable. When created through OpenAPI, the metafield definition is passed in
   • Subsequent apps can modify the metafields definition by Update Metafield Definition, Delete Metafield Definition, and Query Metafield Definition interfaces.
   • Merchants can also modify the metafield definition in the store admin (such as update, delete, query metafields definition).
   • Other apps cannot operate this metafield definition (such as update, delete, query metafields definition).
   • Other apps cannot modify the metafield definition (such as update, delete, query metafields definition).
2. MERCHANT_READ：The store is readable, when the metafield definition is created through OpenAPI
   • Subsequent apps can modify the metafields definition by Update Metafield Definition, Delete Metafield Definition, and Query Metafield Definition interfaces.
   • The merchant can only read this metafield definition (for querying operations) but cannot delete the definition and assign metafield values.
   • Other apps cannot modify the metafield definition (such as update, delete, query metafields definition).
3. PRIVATE：The app is private and can only be created through OpenAPI when your app calls the Create Metafield Definition to create a metafield definition.
   • Subsequent metafield definitions can only be modified by the app Update Metafield Definition, Delete Metafield Definition, and Query Metafield Definition interfaces.

NOTES:

1. In the Create Metafield Definition and Update Metafield Definition interfaces, the Namespace field in the request payload must be in the format: $app:{Namespace}.
   1. Where $app is a fixed character representing created by the app,
   2. {Namespace} is a placeholder that you need to replace with your actual Namespace.
   3. For example, if your namespace is “helloworld”, you need to pass: $app The format of the namespace in the response is: app--$appid--$namespace, where $appid and $namespace are placeholders.
   4. For example, when appId is 123, the value of namespace is: app--123--helloworld.
2. After creating metafields with access permissions, your app can use Update Metafield Definition OOpenAPI to change the access permission value for this metafield definition, such as changing access to MERCHANT_READ_WRITE or MERCHANT_READ.
3. In the future, SHOPLINE will consider adding PUBLIC_READ to the access permission enumeration values, where both merchants and other apps can read these metafields definitions and values.

Undefined metafields​

Undefined Metafields in SHOPLINE are usually created by APP developers using the MetafieldsSet OpenAPI. Merchants may wish to store specific information related to their products, orders, or customers, for which there are no corresponding fields in SHOPLINE's default data model. To meet these specific requirements, merchants can create undefined metafields to store custom data.

When using the MetafieldsSet OpenAPI to batch write metafields data, if the corresponding defined metafield is not found based on the resource object (OwnerResource), Namespace, and Key fields, an undefined Metafield will be written.

It is important to note that currently, undefined metafields can only be processed via the MetafieldsSet OpenAPI, as the SHOPLINE platform does not provide interfaces or functionalities in the admin panel to modify these undefined metafields.

Merchants can rely on the help of developers to implement the desired custom features and ensure proper management and usage of these undefined metafields.

Batch operations on metafields​

When you require a large amount of metafields data to be written, you can use the MetafieldsSet OpenAPI interface. This interface supports passing an array of metafields, with support for up to 25 metafields at once.

When a metafield in the array does not exist, an insert operation will be performed, and when a metafield in the array already exists, an update operation will be performed.

SHOPLINE does not guarantee that both insert and update operations on the passed array of metafields will be successful. Therefore, in the response, the metafields and fail_metafields fields are used to indicate successful and failed data operations, respectively. The fail_metafields in the response contains an errors field that describes the reasons for the errors.

OpenAPI usage examples​

Managing metafield definitions​

Create metafield definition​

OpenAPI URL: https://developer.myshopline.com/docsv2/ec20/cdb180dc069f7d8d6877c0cdffe96f73/zNazo7Sh

curl --location 'https://meiguobingfeng.myshopline.com/admin/openapi/v20230901/metafield_definition.json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiI0ODAyOTNjNWUwZjQ3MmFkNDE0Zjk4MzYyNWUzYzIyY2ViZTZmZTY0Iiwic2VsbGVySWQiOiIyMDAwMjY1MTg3Iiwic3RvcmVJZCI6IjE2NzgxODE0OTU2OTMiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tdXMtcHJlLm15c2hvcGxpbmUuY29tIiwidGltZXN0YW1wIjoxNjg0ODE4NDA3NjA2LCJpc3MiOiJ5c291bCIsImV4cCI6MTc3OTQyNjQwN30.QNX58U0jI7Xx0vamCkAj0oWkH2XwXSBC_hDCXg6ugRzrE9C7tojVnX1qaWxRlIhFGcempdv2WorMfhVBjP-TAw' \
--header 'Content-Type: app/json' \
--data '{
    "definition":{
        "access":{
            "admin":"MERCHANT_READ"
        },
        "name":"Product",
        "namespace":"$app:cl_nor",
        "key":"cst4",
        "description":"A list of ingredients used to make the product.",
        "type":"color",
        "owner_resource":"customers"
    }
}'

Query metafield definition​

OpenAPI URL: https://developer.myshopline.com/docsv2/ec20/cdb180dc069f7d8d6877c0cdffe96f73/BCb1Gayh

curl --location 'https://goodgoods.myshopline.com/admin/openapi/v20230901/metafield_definition.json?id=24458654651' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiJmMjdkNjk4NGM3NTY3ODBiYzBlNDI3MGEwNmM2MGM0ZTY0MDUzZmMyIiwic2VsbGVySWQiOiI0MjAwMTA0MzMzIiwic3RvcmVJZCI6IjE2Nzg4NTA5NzQ2NTEiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwOi8vb3AtZGV2LmR1b3dhbi5jb20iLCJ0aW1lc3RhbXAiOjE2ODQ2NjA1NzM0MjEsImlzcyI6Inlzb3VsIiwiZXhwIjoxNzc5MjY4NTczfQ.eMQZUcftMSlLOerkQKVywhviZCEH1_vGqWjoynGb56-qaoKqifd7VndZX3MRJbUpi7yNERGX77IpD-ud3kO9Xg' \
--header 'Cookie: n_u=cb535e0b966f6a7bdeedb19af7970d69'

Update metafield definition​

OpenAPI URL: https://developer.myshopline.com/docsv2/ec20/cdb180dc069f7d8d6877c0cdffe96f73/77IgysqE

curl --location 'https://meiguobingfeng.myshopline.com/admin/openapi/v20230901/metafield_definition.json?id=72007665693' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiI0ODAyOTNjNWUwZjQ3MmFkNDE0Zjk4MzYyNWUzYzIyY2ViZTZmZTY0Iiwic2VsbGVySWQiOiIyMDAwMjY1MTg3Iiwic3RvcmVJZCI6IjE2NzgxODE0OTU2OTMiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tdXMtcHJlLm15c2hvcGxpbmUuY29tIiwidGltZXN0YW1wIjoxNjg0ODE4NDA3NjA2LCJpc3MiOiJ5c291bCIsImV4cCI6MTc3OTQyNjQwN30.QNX58U0jI7Xx0vamCkAj0oWkH2XwXSBC_hDCXg6ugRzrE9C7tojVnX1qaWxRlIhFGcempdv2WorMfhVBjP-TAw'

Delete metafield definition​

OpenAPI URL: https://developer.myshopline.com/docsv2/ec20/cdb180dc069f7d8d6877c0cdffe96f73/ykEm6cF3

curl --location --request DELETE 'https://meiguobingfeng.myshopline.com/admin/openapi/v20230901/metafield_definition.json?id=72007665693'
 \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiI0ODAyOTNjNWUwZjQ3MmFkNDE0Zjk4MzYyNWUzYzIyY2ViZTZmZTY0Iiwic2VsbGVySWQiOiIyMDAwMjY1MTg3Iiwic3RvcmVJZCI6IjE2NzgxODE0OTU2OTMiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tdXMtcHJlLm15c2hvcGxpbmUuY29tIiwidGltZXN0YW1wIjoxNjg0ODE4NDA3NjA2LCJpc3MiOiJ5c291bCIsImV4cCI6MTc3OTQyNjQwN30.QNX58U0jI7Xx0vamCkAj0oWkH2XwXSBC_hDCXg6ugRzrE9C7tojVnX1qaWxRlIhFGcempdv2WorMfhVBjP-TAw' \
--header 'Content-Type: app/json' \
--data '{
    "delete_all_associated_metafields":true
}'

Managing metafields​

Create metafield​

OpenAPI URL: https://developer.myshopline.com/docsv2/ec20/cdb180dc069f7d8d6877c0cdffe96f73/YEIsskS4

Create an array-type Metafield at the store level

curl --location --request POST 'https://meiguobingfeng.myshopline.com/admin/openapi/v20220901/metafields.json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiI0ODAyOTNjNWUwZjQ3MmFkNDE0Zjk4MzYyNWUzYzIyY2ViZTZmZTY0Iiwic2VsbGVySWQiOiIyMDAwMjY1MTg3Iiwic3RvcmVJZCI6IjE2NzgxODE0OTU2OTMiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tdXMtcHJlLm15c2hvcGxpbmUuY29tIiwidGltZXN0YW1wIjoxNjg0ODE4NDA3NjA2LCJpc3MiOiJ5c291bCIsImV4cCI6MTc3OTQyNjQwN30.QNX58U0jI7Xx0vamCkAj0oWkH2XwXSBC_hDCXg6ugRzrE9C7tojVnX1qaWxRlIhFGcempdv2WorMfhVBjP-TAw' \
--header 'Content-Type: app/json' \
--data-raw '{
    "metafield":{
        "type":"list.single_line_text_field",
        "namespace":"type=crence",
        "key":"cktest4",
        "value":"[\"gid://shopline/Collection/269770817636\"]",
        "description":"chwedohfdwefewfwe",
        "createBy":"chenlin"
    }
}'

{
    "metafield": {
        "updated_at": "2023-05-25T18:16:45+08:00",
        "owner_id": "1678181495693",
        "namespace": "type=crence",
        "created_at": "2023-05-25T18:16:45+08:00",
        "description": "chwedohfdwefewfwe",
        "id": 3074571565693,
        "type": "list.single_line_text_field",
        "owner_resource": "shop",
        "value": "[\"gid://shopline/Collection/269770817636\"]",
        "key": "cktest4"
    }
}

Query metafield​

OpenAPI URL: https://developer.myshopline.com/docsv2/ec20/cdb180dc069f7d8d6877c0cdffe96f73/TiEsxyYK When querying a resource, you can retrieve the metafield information under that resource id. The following example queries the associated metafield value of a specific product:

curl --location --request GET 'https://meiguobingfeng.myshopline.com/admin/openapi/v20220901/metafields/3074571565693.json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiI0ODAyOTNjNWUwZjQ3MmFkNDE0Zjk4MzYyNWUzYzIyY2ViZTZmZTY0Iiwic2VsbGVySWQiOiIyMDAwMjY1MTg3Iiwic3RvcmVJZCI6IjE2NzgxODE0OTU2OTMiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tdXMtcHJlLm15c2hvcGxpbmUuY29tIiwidGltZXN0YW1wIjoxNjg0ODE4NDA3NjA2LCJpc3MiOiJ5c291bCIsImV4cCI6MTc3OTQyNjQwN30.QNX58U0jI7Xx0vamCkAj0oWkH2XwXSBC_hDCXg6ugRzrE9C7tojVnX1qaWxRlIhFGcempdv2WorMfhVBjP-TAw'

{
  "body": {
    "metafield": {
      "created_at": "2022-12-28T09:39:35+00
:00",
      "description": "Customized Description",
      "id": 397923258691,
      "key": "key_123",
      "namespace": "namespace_123",
      "owner_id": "16015223514512351235",
      "owner_resource": "products",
      "type": "single_line_text_field",
      "updated_at": "2022-12-28T09:39:36+00:00",
      "value": "\"gid://shopline/Collection/269770817636\"
    }
  }
}

Update metafield​

OpenAPI URL: https://developer.myshopline.com/docsv2/ec20/cdb180dc069f7d8d6877c0cdffe96f73/nWhOmpKg

curl --location --request PUT 'https://meiguobingfeng.myshopline.com/admin/openapi/v20220901/metafields/3074571565693.json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiI0ODAyOTNjNWUwZjQ3MmFkNDE0Zjk4MzYyNWUzYzIyY2ViZTZmZTY0Iiwic2VsbGVySWQiOiIyMDAwMjY1MTg3Iiwic3RvcmVJZCI6IjE2NzgxODE0OTU2OTMiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tdXMtcHJlLm15c2hvcGxpbmUuY29tIiwidGltZXN0YW1wIjoxNjg0ODE4NDA3NjA2LCJpc3MiOiJ5c291bCIsImV4cCI6MTc3OTQyNjQwN30.QNX58U0jI7Xx0vamCkAj0oWkH2XwXSBC_hDCXg6ugRzrE9C7tojVnX1qaWxRlIhFGcempdv2WorMfhVBjP-TAw' \
--header 'Content-Type: app/json' \
--data '{
    "metafield":{
        "id":3074571565693,
        "value":{
            "amount": "222",
            "currency_code": "EUR"},
        "type":"money",
        "description":"ryueyre"
    }
}'

Delete metafield​

OpenAPI URL: https://developer.myshopline.com/docsv2/ec20/cdb180dc069f7d8d6877c0cdffe96f73/UCbP2ZTD

curl --location --request DELETE 'https://meiguobingfeng.myshopline.com/admin/openapi/v20220901/metafields/3074571565693.json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJhcHBLZXkiOiI0ODAyOTNjNWUwZjQ3MmFkNDE0Zjk4MzYyNWUzYzIyY2ViZTZmZTY0Iiwic2VsbGVySWQiOiIyMDAwMjY1MTg3Iiwic3RvcmVJZCI6IjE2NzgxODE0OTU2OTMiLCJ2ZXJzaW9uIjoiVjIiLCJkb21haW4iOiJodHRwczovL3NsLW9wZW4tdXMtcHJlLm15c2hvcGxpbmUuY29tIiwidGltZXN0YW1wIjoxNjg0ODE4NDA3NjA2LCJpc3MiOiJ5c291bCIsImV4cCI6MTc3OTQyNjQwN30.QNX58U0jI7Xx0vamCkAj0oWkH2XwXSBC_hDCXg6ugRzrE9C7tojVnX1qaWxRlIhFGcempdv2WorMfhVBjP-TAw' \
--header 'Content-Type: app/json'

Bulk write metafields​

OpenAPI URL: https://developer.myshopline.com/docsv2/ec20/cdb180dc069f7d8d6877c0cdffe96f73/zHCaVw80

• Bulk write metafields

curl -L -X POST 'https://openapiceshidianpu.myshopline.com/admin/openapi/v20230901/metafields_set.json' \
-H 'Content-Type: app/json' \
-H 'Accept: app/json' \
--data-raw '{
  "metafields": [
    {
      "description": "Customized Description",
      "key": "mfkey-1",
      "namespace": "mftest",
      "owner_id": "16058986610866520712462605",
      "owner_resource": "products",
      "type": "list.number_decimal",
      "value": "[\"0.123\",\"22.33\"]"
    },
    {
      "description": "Customized Description",
      "key": "mfkey-2",
      "namespace": "mftest",
      "owner_id": "2241475414",
      "owner_resource": "customers",
      "type": "multi_line_text_field",
      "value": "\"gid://shopline/Collection/269770817636\"
    }
  ]
}'

{
  "body": {
    "fail_metafields": [],
    "metafields": [
      {
        "created_at": "2023-05-31T17:03:43+08:00",
        "description": "Description of metafield definitions.",
        "id": 3152668027083,
        "key": "mfkey-2",
        "namespace": "mftest",
        "owner_id": "2241475414",
        "owner_resource": "customers",
        "type": "multi_line_text_field",
        "updated_at": "2023-05-31T17:03:43+08:00",
        "value": "This is the metafields assignment content"
      },
      {
        "created_at": "2023-05-31T17:03:43+08:00",
        "description": "Description of Meta Field Definitions-1",
        "id": 3152668017083,
        "key": "mfkey-1",
        "namespace": "mftest",
        "owner_id": "16058986610866520712462605",
        "owner_resource": "products",
        "type": "list.number_decimal",
        "updated_at": "
2023-05-31T17:03:43+08:00",
        "value": "[\"0.123\",\"22.33\"]"
      }
    ]
  }
}

Common usage questions​

Manually importing GMC fields from spreadsheets​

Local product data can be exported using the following steps:

1. Export the product data in a spreadsheet format.
2. Add the necessary GMC fields columns to the exported spreadsheet at the product level. If there are multiple styles, these GMC fields should be placed in the first row of each corresponding product.

The data for the GMC fields is obtained from metafields, and these fields have fixed names.

When importing the product data with the above GMC fields:

• There will be no formatting validation for the data in the spreadsheet. Whatever values are present in the table will be written to the corresponding MF fields.
• When the GMC field column is empty, no clearing action will be performed. Regardless of whether the overwrite option is selected or not, empty fields will not be altered. Only when there are values present will the update be performed.

Metafields SEO data optimization​

Value of meta tags (TDK)​

Meta tags are text snippets that describe the content of a webpage. They usually consist of Meta Title, Meta Description, and Meta Keywords, often referred to as "TDK."

Meta tags do not appear on the web page itself, but in the page's source code. Meta tags are essentially content descriptors that help inform search engines like Google about the content of the webpage.

Optimizing the meta tags (TDK) of URLs within a store is beneficial for Google spiders to crawl, analyze, index, and improve the natural ranking on SERPs (Search Engine Results Pages). You can use OpenAPI to add, modify, query, or delete SEO TDK data for all resources that have SEO information.

Prerequisites​

• Familiarity with metafields and how they work.
• Understanding of metafield's OpenAPI.

Managing SEO information​

You can manage the SEO information of resources through the merchant's back-end.

For example, after creating a product in the merchant's back-end, the meta_title and meta_description of the product detail page will be automatically populated with the product's title and description.

You have two methods to customize the page title, description, and search engine keywords for the product detail page:

1. Edit the SEO information of the corresponding resource page through the merchant's back-end.
2. Edit the SEO information of the corresponding resource page through Metafield's OpenAPI.

The meta_title, meta_description, and meta_keyword of the page are stored in the metafield with the namespace "seo" and the type "single_line_text_field".

Editing SEO information for the corresponding resource page through metafield's OpenAPI​

Step 1: Use the Metafield's API for paginating primary resources to query the metafieldDefinitionId for the SEO metafields.

Step 2: Use the Metafield's API for editing primary resources to edit the SEO information, following the storage format for SEO resources:

• Namespace: seo
• Keys: seoTitle, seoDescription, seoKeyword
• Resources:
  • Home Page: shop (The homepage SEO resource uses the shop resource's Metafield query/edit interface)
  • Products: products
  • Collections: collections
  • Blog Groups: blogs
  • Blogs: articles
  • Custom Pages: pages
• Type: single_line_text_field