Create Shopify Metafield Definition
POST/api/shopify/:integrationInstance/metafield-definitions
Creates a metafield definition in the Shopify store and returns it. Use it to send data the store has no metafield for yet.
integrations:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token and permission to update integrations.
Request body:
- name (required, max 255)
- namespace (default
custom; letters, numbers, dashes and underscores;shopifyand app-reserved namespaces are rejected) - key (required, 2-64 chars, lowercase letters, numbers and underscores; unique per owner and namespace)
- owner_type (required):
productorvariant - type (required): a Shopify metafield type SKU.io can send, e.g.
single_line_text_field,multi_line_text_field,rich_text_field,number_integer,number_decimal,boolean,date,date_time,url,color,weight,dimension,volume,money,rating,json,product_reference,variant_reference,collection_reference,metaobject_reference,file_reference, or alist.form of the listable ones - description (optional, max 1000)
- choices (optional, max 128 distinct strings; applies to single line text types only)
- storefront_visible (optional, default true): whether themes can read the metafield
Errors: 422 for invalid input, or when Shopify refuses the definition (e.g. the key already exists).
Request
Responses
- 201
- 401
- 403
- 404
- 422
- 429
Created
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Unprocessable Content
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.