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

# Author property and tag mappings

> Preview and author a managed source mapping from publisher properties or tags to ad-server targeting

Property and tag mappings let a seller record how a live publisher property, or
properties carrying a publisher-attested tag, is addressed in the connected
ad server. A mapping targets one of:

* `key_value` - an ad-server custom-targeting key and value, such as
  `site_code=food`.
* `ad_unit` - an ad-unit external id.
* `placement` - a placement external id.

The mapping is source-scoped. It is an execution address, not an authorization
record and not a buyer-coverage declaration. Publisher authorization continues
to come from the seller's identity and property sources, and buyer-visible
coverage is represented separately by publisher properties.

## Inputs

Use the complete mapping set for one managed ad-server source. A property row
requires `propertyExternalId` and `publisherDomain`; a tag row requires `tag`.
Key-value rows require `signalKey` and `signalValue`. Ad-unit and placement
rows require `selectorExternalId` instead.

```json theme={null}
{
  "grain": "tag",
  "tag": "raptive_food",
  "targetKind": "key_value",
  "signalKey": "site_code",
  "signalValue": "12345"
}
```

The first Raptive vertical slice accepts seller-supplied vertical -> `site_code`
definitions such as this one. It records the vertical definition; it does not
invent a static per-site map from a vertical label.

## Preview

Read the current set:

```bash theme={null}
curl "https://api.interchange.io/api/v2/storefront/inventory-sources/$SOURCE_ID/property-mappings" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
```

Preview a proposed replacement with `dry_run=true`:

```bash theme={null}
curl -X PUT "https://api.interchange.io/api/v2/storefront/inventory-sources/$SOURCE_ID/property-mappings?dry_run=true" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [{
      "grain": "tag",
      "tag": "raptive_food",
      "targetKind": "key_value",
      "signalKey": "site_code",
      "signalValue": "12345"
    }],
    "provenance": {
      "source": "import",
      "reference": "raptive-verticals.csv"
    }
  }'
```

The preview validates each property or tag against the current authorized
property set, rejects duplicate mapping keys, checks key-values against the
live signal catalog, and checks ad-unit or placement ids against the live
source capabilities. Freeform keys accept a non-empty seller value; predefined
keys require an exact live child value. It returns separate `mapped` and
`unmapped` rows plus `keyValueValidation` and `selectorValidation`; fix every
blocking row before replacing the set.

## Confirmed replacement

Replacement is a full replacement, not an append. After reviewing the dry-run
results, send the same complete set with provenance and `confirmed: true`:

```bash theme={null}
curl -X PUT "https://api.interchange.io/api/v2/storefront/inventory-sources/$SOURCE_ID/property-mappings?dry_run=false" \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mappings": [{
      "grain": "tag",
      "tag": "raptive_food",
      "targetKind": "key_value",
      "signalKey": "site_code",
      "signalValue": "12345"
    }],
    "provenance": {
      "source": "import",
      "reference": "raptive-verticals.csv"
    },
    "confirmed": true
  }'
```

Every confirmed replacement records the provenance, confirming operator, and
validation timestamp. In Murph, use the typed list, dry-run, and replacement
tools. Murph shows the full replacement and waits for explicit confirmation
before calling the replacement tool; a plain "yes" does not bypass that gate.

## Current boundary

This slice stores and validates seller mappings. It does not claim that
downstream media-buy execution consumes them yet. Do not promise that a buyer's
property list or vertical will be enforced on the media-buy leg until the
follow-on execution work is shipped. Mappings also do not grant authorization,
expand buyer coverage, or establish that a buyer is eligible to purchase an
inventory subset.

## Related

<CardGroup cols={2}>
  <Card title="Publisher properties and coverage" href="/v2/storefront/inventory-sources/publisher-properties-coverage" icon="globe">
    How buyer-visible coverage is derived from publisher identity
  </Card>

  <Card title="Custom targeting and properties" href="/v2/storefront/esa/custom-targeting-properties" icon="sliders">
    How ad-server key-values relate to properties and signals
  </Card>

  <Card title="Create products from inventory" href="/v2/storefront/inventory-sources/create-products" icon="rectangle-ad">
    Package synced inventory into sellable products
  </Card>
</CardGroup>