Skip to main content

​
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

CodeDescription
UNAUTHORIZEDInvalid or missing JWT
FORBIDDENWrong store / insufficient role
VALIDATION_ERRORTop-level body shape is wrong (per-row errors are returned in results[])