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

# List Metafields

> List the metafields your app has written

# List Metafields

Returns metafields written by **your app** (scoped by `appId`). Filter by
owner type, owner id, namespace, or key.

<Note>
  This endpoint returns only the metafields your app has written. To list
  all metafields on a resource (including those written by other apps or
  merchants), the merchant must use the Admin API
  (`GET /metafields?ownerType=...&ownerId=...`).
</Note>

## Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.launchmystore.io/api/v1/metafields.json?ownerType=product&ownerId=<productId>" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const url = new URL('https://api.launchmystore.io/api/v1/metafields.json');
  url.searchParams.set('ownerType', 'product');
  url.searchParams.set('ownerId', productId);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const { data } = await response.json();
  ```
</CodeGroup>

## Required scope

`read_metafields`

## Query parameters

<ParamField query="ownerType" type="string">
  Filter by owner type. One of `shop`, `product`, `variant`, `collection`,
  `customer`, `order`, `page`, `blog`, `article`. **Lowercase only.**
</ParamField>

<ParamField query="ownerId" type="string">
  Filter by the owning resource id. Required for every owner type *except*
  `shop`.
</ParamField>

<ParamField query="namespace" type="string">
  Filter by namespace.
</ParamField>

<ParamField query="key" type="string">
  Filter by exact key.
</ParamField>

<ParamField query="page" type="integer" default="1">
  1-indexed page number.
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Items per page. Max 250.
</ParamField>

## Response

<ResponseField name="status" type="integer">
  HTTP status code (200 on success).
</ResponseField>

<ResponseField name="state" type="string">
  `success` or `error`.
</ResponseField>

<ResponseField name="data.metafields" type="array">
  Array of metafield objects.

  <Expandable title="Metafield Object">
    <ResponseField name="id" type="string">UUID</ResponseField>
    <ResponseField name="namespace" type="string">e.g. `custom`</ResponseField>
    <ResponseField name="key" type="string">e.g. `warranty_years`</ResponseField>
    <ResponseField name="value" type="any">decoded value — integers/booleans/objects/arrays for compound types, raw string for scalars</ResponseField>
    <ResponseField name="raw_value" type="string">canonical wire form (the stored string, before decoding)</ResponseField>
    <ResponseField name="type" type="string">one of the 22 [supported types](/api-reference/metafields/overview#supported-types-22)</ResponseField>
    <ResponseField name="owner_type" type="string">resource kind</ResponseField>
    <ResponseField name="owner_id" type="string">resource id</ResponseField>
    <ResponseField name="app_id" type="string">your app's id (always your own)</ResponseField>
    <ResponseField name="created_at" type="string">ISO timestamp</ResponseField>
    <ResponseField name="updated_at" type="string">ISO timestamp</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.total" type="integer">Total matching records.</ResponseField>
<ResponseField name="data.page" type="integer">Current page.</ResponseField>
<ResponseField name="data.limit" type="integer">Page size.</ResponseField>

## Example response

```json theme={null}
{
  "status": 200,
  "state": "success",
  "data": {
    "metafields": [
      {
        "id": "e607f43e-9251-451e-a45c-38bf28d61154",
        "namespace": "custom",
        "key": "badge",
        "value": "BESTSELLER",
        "raw_value": "BESTSELLER",
        "type": "single_line_text_field",
        "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"
      },
      {
        "id": "48b24b31-b1a4-4997-9827-a1668a886ea6",
        "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"
      }
    ],
    "total": 2,
    "page": 1,
    "limit": 50
  }
}
```

## Error codes

| Code               | Description                              |
| ------------------ | ---------------------------------------- |
| `UNAUTHORIZED`     | Invalid or missing access token          |
| `FORBIDDEN`        | App doesn't have `read_metafields` scope |
| `VALIDATION_ERROR` | Invalid `ownerType` value                |