import MetafieldFields from "../../../src/reference/subbly-sdk/types/Metafield.mdx";
import PaginationFields from "../../../src/reference/subbly-sdk/types/Pagination.mdx";

<SdkPage group="metafields" />

<Method id="list" signature="subbly.metafield.list(params)">

Gets a page of the metafield definitions of the shop. Metafields are the custom
fields a shop adds to a customer, a subscription or a product. Read them to
build your own form, then write the answers back as `metadata` on the cart or
on a subscription.

The namespace is singular: `subbly.metafield`, not `subbly.metafields`.

<Params>
  <Param name="params" required type="MetafieldListParams">
    Which definitions to return. The argument is required by position, so pass
    an empty object for the defaults.
    <Properties label="params">
      <Param name="ids" optional type="number[]">
        Keep only these metafield IDs.
      </Param>

      <Param name="slugs" optional type="string[]">
        Keep only these slugs.
      </Param>

      <Param name="page" optional type="number">
        Page to return, counted from 1.
      </Param>

      <Param name="perPage" optional type="number">
        How many definitions per page.
      </Param>

      <Param name="preset" optional type="boolean">
        `true` keeps only preset fields, which hold a fixed list of choices.
        `false` keeps only free-text fields.
      </Param>

      <Param name="expand" optional type="string[]">
        Relations to include in the response.
      </Param>
    </Properties>
  </Param>
</Params>

<Returns type="Promise<MetafieldListResponse>">
One page of definitions.
<Properties>
  <Param name="data" type="Metafield[]">
    The definitions on this page.
    <Properties label="metafield" collapsed>
      <MetafieldFields />
    </Properties>
  </Param>

  <Param name="pagination" type="Pagination">
    Where this page sits in the full list.
    <Properties label="pagination" collapsed>
      <PaginationFields />
    </Properties>
  </Param>
</Properties>
</Returns>

<Example>

```js title="List the metafields"
const { data, pagination } = await subbly.metafield.list({
  page: 1,
  perPage: 20
})
```

```js title="Load one definition by slug"
const { data } = await subbly.metafield.list({ slugs: ['coffee-strength'] })
const [strength] = data
```

</Example>

</Method>