# Sponsored products

Sell a brand the first place in a search, mark the product as an ad on the storefront, and count its views and clicks for the campaign report.

A sponsored product is a [pin](/docs/reference/glossary#pin) with a campaign: a brand pays for a place, a rule puts its product there, and the campaign names the deal. Here Halvard pays for the first place in every sofa search:

```json title="rules.json"
{
    "id": "halvard-autumn",
    "description": "Halvard pays for the first place in sofa searches",
    "when": { "query": { "contains": "sofa" } },
    "then": {
        "pin": [{ "entity": "product:SOFA-VIDAR-ECK", "position": 1, "sponsored": { "campaign": "Halvard autumn" } }]
    }
}
```

The campaign is your name for the deal, one line of up to 200 characters, and the campaign report counts by it. A [schedule](/docs/rules#schedules) runs the rule for the weeks the brand paid for.

**Reference:** [`sponsored`](/docs/reference/release-files/rules#then.pin.sponsored) · [`pin`](/docs/reference/release-files/rules#then.pin)

## Mark it as an ad

The answer marks the hit with `sponsored`, `{ "campaign": "Halvard autumn" }`. A storefront must show such a tile as an ad and name the campaign in its clicks and views:

- **The React components** do both: the tile's name starts with "Anzeige" (ad), and its reports carry the campaign ([React components](/docs/react#every-ad-is-marked)).
- **A storefront of your own** labels the tile itself and reports with the hit's campaign, such as `search.report.click({ query_id, entity, position, campaign })` ([Clicks and views](/docs/clicks-and-views)).

**Insights → Campaigns** in the panel counts each campaign's views and clicks over the days you choose, and downloads them as a CSV for the brand ([Insights](/docs/insights)).

**Reference:** [hit `sponsored`](/docs/reference/query-api#search.answer.sections.hits.sponsored) · [`GET /api/v1/insights/campaigns`](/docs/reference/management-api#show-campaigns)

## Add a sponsored product

A sponsored pin is added as any [rule](/docs/rules) is, in a [draft](/docs/reference/glossary#draft) that shoppers see nothing of until you publish it.

**In the panel:**

1. In **Merchandising → Rules**, press **Start a draft**, then **New rule**.
2. Under **Applies to**, choose **Searches that contain words**, type `sofa` under **Words** and press Enter.
3. Choose **Add an effect** → **Pin products**, and pick "Vidar Ecksofa mit Schlaffunktion" (corner sofa bed) under **Add a product**.
4. Switch on **Sponsored** under it, and type `Halvard autumn` into the campaign's field, which takes the focus.
5. **Save**, then **Review and publish**.

A sponsored pin without a campaign is not saved, and switching **Sponsored** off makes it an unpaid pin again. The list then sums the rule up as a pin of the Vidar "as a sponsored placement of “Halvard autumn”".

**Through the API:**

Start a draft with the store's export, then add the rule with its campaign:

```sh title="Terminal"
draft=$(curl -s -X POST -H "Authorization: Bearer $key" -H 'Content-Type: application/x-ndjson' \
  --data-binary @tests/fixtures/home/catalog.jsonl "$api/imports?name=catalog.jsonl" | jq -r .import.id)
version=$(curl -s -H "Authorization: Bearer $key" $api/imports/$draft | jq -r .version)
jq -n --arg version "$version" '{version: $version, id: "halvard-autumn",
    name: "Halvard pays for the first place in sofa searches",
    fields: {when: {trigger: {kind: "query", matching: "contains", phrases: ["sofa"]}},
      then: {pin: [{entity: "product:SOFA-VIDAR-ECK", position: 1, sponsored: {campaign: "Halvard autumn"}}]}}}' \
  | curl -s -H "Authorization: Bearer $key" -H 'Content-Type: application/json' -d @- $api/imports/$draft/rules \
  | jq -r '.rules.rules[0].summary'
```

```text title="Answer: 201 · 68 ms"
Pins Vidar Ecksofa mit Schlaffunktion to 1 as a sponsored placement of “Halvard autumn” for searches containing "sofa"
```

Open the search page for "sofa" with the draft's files, and read the pin in the trace:

```sh title="Terminal"
body=$(curl -s -H "Authorization: Bearer $key" $api/imports/$draft | jq '{url: "/suche?q=sofa&redirect=0", files}')
curl -s -H "Authorization: Bearer $key" -H 'Content-Type: application/json' -d "$body" $api/preview/page \
  | jq -c '.results.trace.steps[] | select(.step == "rules") | .rules[0].effects[] | {target, placed}'
```

```json title="Answer: 200 · 8.4 ms · release 3774ab70"
{"target":"product:SOFA-VIDAR-ECK as a sponsored placement of “Halvard autumn”","placed":1}
```

The hit carries `sponsored` once the draft is live. A preview searches the live index, which holds no engine rule for the new pin yet, so it finds the Vidar unpaid in its own place.

Publish the draft with `POST $api/imports/$draft/publish`, or discard it:

```sh title="Terminal"
curl -s -X DELETE -H "Authorization: Bearer $key" $api/imports/$draft | jq -r .state
```

```text title="Answer: 200 · 17 ms"
discarded
```

**Reference:** [`POST .../rules`](/docs/reference/management-api#create-rule) · [`Pin`](/docs/reference/management-api#Pin)

## Where it stands

A sponsored pin is placed as any pin is:

- **Once, at its position.** The product shows nowhere else in the list.
- **Only where it belongs.** It shows where it meets the page's category, the shopper's filters and the rules' filters, so a filter never brings an ad that misses it.
- **A hide or a higher pin wins.** A hide of the product beats it, and a higher rule's unpaid pin of the same product takes its place, so the hit is no ad.
- **Like any pin in the order.** Two pins for one position settle as on [Rules](/docs/rules#who-wins), and it counts toward the 100 pins per section a request switches on.

A rule with a sponsored pin is never a category page's grid, so it stays on the Rules screen. The hit's `why` says "A sponsored placement of “Halvard autumn”, pinned to position 1 by the rule “Halvard pays for the first place in sofa searches”."

**Reference:** [`pins_per_query`](/docs/reference/limits#pins_per_query) · [`rank` step](/docs/reference/trace#rank)

## Next

- [Rules](/docs/rules): conditions, schedules and who wins.
- [Insights](/docs/insights): the campaign report and its CSV.
- [Clicks and views](/docs/clicks-and-views): report a tile's views and clicks.