> ## 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.

# Update Metafield

> Update value or type of an existing metafield by id

# Update Metafield

Updates the value (and optionally type) of a metafield owned by **your
app**. The metafield is matched by id and `appId` — you cannot update
metafields written by other apps or by merchants.

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT "https://api.launchmystore.io/api/v1/metafields/<metafieldId>.json" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "value": "NEW BADGE VALUE",
      "type": "single_line_text_field"
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(`https://api.launchmystore.io/api/v1/metafields/${id}.json`, {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      value: 'NEW BADGE VALUE',
      type: 'single_line_text_field',
    }),
  });
  ```
</CodeGroup>

## Required scope

`write_metafields`

## Path parameters

<ParamField path="id" type="string" required>
  The metafield's UUID (the `id` field from list/create responses).
</ParamField>

## Body parameters

<ParamField body="value" type="any">
  The new value. Scalars sent as-is; compounds sent as JSON. Must validate
  against the (current or new) `type`.
</ParamField>

<ParamField body="type" type="string">
  Optional new type. The new value must validate against it.
</ParamField>

<Note>
  `namespace`, `key`, `ownerType`, and `ownerId` **cannot** be changed.
  Create a new metafield and delete the old one if you need to move it.
</Note>

## Examples

### Change a scalar value

```bash theme={null}
curl -X PUT "https://api.launchmystore.io/api/v1/metafields/<id>.json" \
  -H "Authorization: Bearer ..." \
  -H "Content-Type: application/json" \
  -d '{ "value": "NEW BADGE VALUE" }'
```

### Update a compound value

```bash theme={null}
curl -X PUT "https://api.launchmystore.io/api/v1/metafields/<id>.json" \
  -H "Authorization: Bearer ..." \
  -H "Content-Type: application/json" \
  -d '{ "value": { "amount": "19.99", "currency_code": "USD" }, "type": "money" }'
```

### Update a list

```bash theme={null}
curl -X PUT "https://api.launchmystore.io/api/v1/metafields/<id>.json" \
  -H "Authorization: Bearer ..." \
  -H "Content-Type: application/json" \
  -d '{ "value": ["red", "limited"], "type": "list.single_line_text_field" }'
```

## Response

```json theme={null}
{
  "status": 200,
  "state": "success",
  "data": {
    "metafield": {
      "metafieldId": "e607f43e-9251-451e-a45c-38bf28d61154",
      "namespace": "custom",
      "key": "badge",
      "value": "NEW BADGE VALUE",
      "type": "single_line_text_field",
      "ownerType": "product",
      "ownerId": "e5f6a7b8-9c0d-4e1f-a2b3-c4d5e6f7a8b9",
      "appId": "your-app-id",
      "createdAt": "2026-05-09T13:32:53.135Z",
      "updatedAt": "2026-05-09T13:42:50.402Z"
    }
  }
}
```

## Cache invalidation

A successful update automatically expires the storefront caches for the
owning resource. The next render sees the new value.

## Error codes

| Code | Description |
| - | - |
| `UNAUTHORIZED` | Invalid or missing access token |
| `FORBIDDEN` | App doesn't have `write_metafields` scope |
| `NOT_FOUND` | Metafield does not exist, or wasn't written by your app |
| `VALIDATION_ERROR` | Value doesn't match the (new) type or its validations |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.