Bulk Upsert Metafields

This endpoint is available on the Admin API (merchant JWT) only. It is not exposed to OAuth-scoped apps. Apps must call POST /api/v1/metafields.json once per field.

Upsert N metafields in a single request. This is what powers the the admin “Save” button on resource detail pages — when a merchant edits multiple metafields and clicks save, the editor sends one bulk request instead of N individual calls.

Request

curl -X POST "https://api.launchmystore.io/metafields/bulk" \
  -H "Authorization: Bearer <merchant-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "metafields": [
      { "namespace": "custom", "key": "badge",          "type": "single_line_text_field", "value": "BESTSELLER",        "ownerType": "product", "ownerId": "..." },
      { "namespace": "custom", "key": "warranty_years", "type": "number_integer",         "value": 5,                   "ownerType": "product", "ownerId": "..." },
      { "namespace": "custom", "key": "care",           "type": "rich_text_field",        "value": "<p>Hand wash.</p>", "ownerType": "product", "ownerId": "..." }
    ]
  }'

Auth

Merchant JWT (owner, or staff with admin/manager access).

Body

metafields

array

required

Array of metafield objects. Each item has the same shape as POST /metafields.

Each item is upserted independently, keyed by (owner type, namespace, key, owner). If one item fails validation, the others still proceed (per-item error reporting in the response).

Response

{
  "status": 200,
  "state": "success",
  "data": {
    "results": [
      { "ok": true, "metafield": { "id": "...", "key": "badge", ... } },
      { "ok": true, "metafield": { "id": "...", "key": "warranty_years", ... } },
      { "ok": false, "error": { "field": "value", "message": "value must be valid hex color" } }
    ],
    "succeeded": 2,
    "failed": 1
  }
}

Cache invalidation

The cache invalidation chain fires once after the whole batch completes — not once per row. A 50-item save costs a single cache invalidation, which makes bulk the right call for editor-style “save all” flows.

Error codes

Code	Description
`UNAUTHORIZED`	Invalid or missing JWT
`FORBIDDEN`	Wrong store / insufficient role
`VALIDATION_ERROR`	Top-level body shape is wrong (per-row errors are returned in `results[]`)

Delete Metafield Metafield Definitions Overview

​Bulk Upsert Metafields

​Request

​Auth

​Body

​Response

​Cache invalidation

​Error codes

Bulk Upsert Metafields

Request

Auth

Body

Response

Cache invalidation

Error codes