> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecharlie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Metafields reference

> Every metafield Charlie writes, where to read it from, and which namespace to use

Charlie writes safety-stock–adjusted inventory data to two metafield namespaces. Use the right one for your integration.

## Which namespace to use

| Integration                             | Namespace                  | Why                                            |
| --------------------------------------- | -------------------------- | ---------------------------------------------- |
| Themes (Liquid or Storefront API)       | `app--{APP_ID}--inventory` | Variant-level fields are only here             |
| Product feeds (GMC, Meta, Lengow, etc.) | `charlie_inventory`        | Public, same key on every store                |
| Search & Discovery filters              | `charlie_inventory`        | Smart collection conditions + admin filterable |
| Smart collections                       | `charlie_inventory`        | Same as above                                  |
| Admin API integrations (other apps)     | `charlie_inventory`        | Other apps can't read app-reserved namespaces  |

## Finding your app namespace

The `app--{APP_ID}--inventory` namespace is unique per store. Find your app ID once and reuse it everywhere.

<Steps>
  <Step title="Open metafield definitions">
    Shopify Admin → Settings → Custom data → Metafields → Variants.
  </Step>

  <Step title="Open a Charlie metafield">
    Click any metafield with key `inventory.available` or `inventory.fulfillable`.
  </Step>

  <Step title="Copy the namespace">
    Copy the full namespace, e.g. `app--303723511809--inventory`.
  </Step>
</Steps>

## `app--{APP_ID}--inventory` (app-reserved)

Use for themes. Includes variant-level fields.

### Shop

| Key                    | Type      | Value                                                           |
| ---------------------- | --------- | --------------------------------------------------------------- |
| `safety_stock_enabled` | `boolean` | Master switch. `true` when safety stock is active for this shop |

### Variant

| Key           | Type             | Value                                                |
| ------------- | ---------------- | ---------------------------------------------------- |
| `available`   | `boolean`        | `true` if sellable quantity > 0 for this variant     |
| `fulfillable` | `number_integer` | Total sellable quantity across fulfillable locations |

### Product

| Key                       | Type                | Value                                           |
| ------------------------- | ------------------- | ----------------------------------------------- |
| `available`               | `boolean`           | `true` if any variant has sellable quantity > 0 |
| `fulfillable`             | `number_integer`    | Total fulfillable across all variants           |
| `first_available_variant` | `variant_reference` | First variant with sellable quantity > 0        |

## `charlie_inventory` (public)

Use for feeds, filters, smart collections, and any non-theme integration. Same namespace on every store. No app ID lookup needed.

Themes can read either namespace. **Other apps cannot read the `app--{APP_ID}--inventory` (app-reserved) namespace.** That's why Charlie mirrors product-level availability to a public namespace. Anything that runs as a Shopify app (Search & Discovery, product feed apps, smart collection metafield conditions, third-party search) can only see `charlie_inventory`.

### Product

| Key           | Type             | Value                                           |
| ------------- | ---------------- | ----------------------------------------------- |
| `available`   | `boolean`        | `true` if any variant has sellable quantity > 0 |
| `fulfillable` | `number_integer` | Total fulfillable across all variants           |

<Note>
  Variant-level fields are not mirrored to `charlie_inventory`. For variant-level data, use the app-reserved namespace.
</Note>

### Access

**Liquid:**

```liquid theme={"system"}
{% assign is_available = product.metafields.charlie_inventory.available.value %}
{% assign sellable = product.metafields.charlie_inventory.fulfillable.value %}
```

**Storefront API:**

```graphql theme={"system"}
query ($handle: String!) {
  product(handle: $handle) {
    available: metafield(namespace: "charlie_inventory", key: "available") { value }
    fulfillable: metafield(namespace: "charlie_inventory", key: "fulfillable") { value }
  }
}
```

## Update timing

Charlie writes both namespaces whenever Shopify sends a `products/update` webhook (which fires on inventory changes). Updates are queued and applied within a few seconds, max \~10 seconds.

## After uninstalling Charlie

Charlie does not delete `charlie_inventory.*` metafield values when uninstalled. The values stay on each product so you can export or migrate the data.

To remove them, delete the metafield definitions manually in **Shopify Admin → Settings → Custom data → Products** (look for `charlie_inventory.available` and `charlie_inventory.fulfillable`).

## Related

<CardGroup cols={2}>
  <Card title="Theme integration" icon="palette" href="/inventory/theme-integration">
    Liquid recipes for variant pickers, badges, and price display
  </Card>

  <Card title="App integrations" icon="plug" href="/inventory/app-integrations">
    Wire product feeds, search, and filter apps to respect safety stock
  </Card>

  <Card title="Safety Stock" icon="shield" href="/inventory/safety-stock">
    How sellable inventory is calculated
  </Card>
</CardGroup>