Skip to main content
POST
/
api
/
v1
/
metafields.json
Create or Upsert Metafield
curl --request POST \
  --url https://api.launchmystore.io/api/v1/metafields.json \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "namespace": "<string>",
  "key": "<string>",
  "type": "<string>",
  "value": "<any>",
  "ownerType": "<string>",
  "ownerId": "<string>"
}
'
{
  "status": 123,
  "state": "<string>",
  "data.metafield": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt

Use this file to discover all available pages before exploring further.

​
Create or Upsert Metafield

This endpoint upserts: if a metafield with the same (ownerType, namespace, key, ownerId) already exists for your app, the value is updated; otherwise a new row is created. The unique constraint guarantees one metafield per (resource, namespace, key) per app.

​
Request

curl -X POST "https://api.launchmystore.io/api/v1/metafields.json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "custom",
    "key": "warranty_years",
    "type": "number_integer",
    "value": 5,
    "ownerType": "product",
    "ownerId": "94995c07-e8a5-43f2-9d1a-18ccf8199adf"
  }'

​
Required scope

write_metafields

​
Body parameters

​
namespace
string
required
Namespace. Use your app handle (e.g. subscriptions_pro) — custom is the merchant-managed namespace.
​
key
string
required
Field key. Unique per (ownerType, namespace, ownerId).
​
type
string
required
One of the 22 supported types. Determines how value is validated and decoded.
​
value
any
required
The value. Scalars are sent as-is (string, number, boolean). Compound types (weight, dimension, volume, money, rating, lists, JSON) are sent as JSON.
​
ownerType
string
required
One of shop, product, variant, collection, customer, order, page, blog, article. Lowercase only.
​
ownerId
string
required
The id of the owning resource. Required for every owner type except shop.

​
Examples by type

​
Scalar text

{
  "namespace": "custom",
  "key": "badge",
  "type": "single_line_text_field",
  "value": "BESTSELLER",
  "ownerType": "product",
  "ownerId": "..."
}

​
Number with validation

{
  "namespace": "custom",
  "key": "warranty_years",
  "type": "number_integer",
  "value": 5,
  "ownerType": "product",
  "ownerId": "..."
}

​
Boolean

{
  "namespace": "custom",
  "key": "is_featured",
  "type": "boolean",
  "value": true,
  "ownerType": "product",
  "ownerId": "..."
}

​
Rich text (HTML, rendered unescaped in Aqua)

{
  "namespace": "custom",
  "key": "care_instructions",
  "type": "rich_text_field",
  "value": "<p>Hand wash only.</p>",
  "ownerType": "product",
  "ownerId": "..."
}

​
Measurement

{
  "namespace": "specs",
  "key": "weight",
  "type": "weight",
  "value": { "unit": "KILOGRAMS", "value": 1.2 },
  "ownerType": "product",
  "ownerId": "..."
}

​
Money

{
  "namespace": "custom",
  "key": "deposit",
  "type": "money",
  "value": { "amount": "12.50", "currency_code": "USD" },
  "ownerType": "product",
  "ownerId": "..."
}

​
Reference

{
  "namespace": "custom",
  "key": "matching_collection",
  "type": "collection_reference",
  "value": "8b3e2c10-...",
  "ownerType": "product",
  "ownerId": "..."
}

​
List

{
  "namespace": "custom",
  "key": "tags",
  "type": "list.single_line_text_field",
  "value": ["red", "limited", "sale"],
  "ownerType": "product",
  "ownerId": "..."
}

​
JSON (free-form structured data)

{
  "namespace": "custom",
  "key": "specifications",
  "type": "json",
  "value": {
    "dimensions": { "width": 10, "height": 15, "depth": 5 },
    "weight": "0.5kg"
  },
  "ownerType": "product",
  "ownerId": "..."
}

​
Response

​
status
integer
201 if created, 200 if updated.
​
state
string
success or error.
​
data.metafield
object
The created or updated metafield. See List Metafields for shape.

​
Example response

{
  "status": 201,
  "state": "success",
  "data": {
    "metafield": {
      "id": "e607f43e-9251-451e-a45c-38bf28d61154",
      "namespace": "custom",
      "key": "warranty_years",
      "value": 5,
      "raw_value": "5",
      "type": "number_integer",
      "owner_type": "product",
      "owner_id": "94995c07-e8a5-43f2-9d1a-18ccf8199adf",
      "app_id": "your-app-id",
      "created_at": "2026-05-09T13:32:53.135Z",
      "updated_at": "2026-05-09T13:32:53.135Z"
    }
  }
}

​
Validation errors

{
  "statusCode": 400,
  "message": "Metafield value validation failed",
  "errors": [
    { "field": "value", "message": "value must be <= 25" }
  ]
}

​
Cache invalidation

A successful upsert automatically expires:
  • Backend Redis caches: g:{storeId}:{ownerType}:{handle}
  • LaunchMyStore frontend PageHtmlCache
The next storefront render sees the new value.

​
Error codes

CodeDescription
UNAUTHORIZEDInvalid or missing access token
FORBIDDENApp doesn’t have write_metafields scope
VALIDATION_ERRORType or validation rule failed (see errors[])
NOT_FOUNDOwning resource does not exist (when reference verification is enabled)