Sponsored products

A sponsored product is a 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:

{
    "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 runs the rule for the weeks the brand paid for.

Reference: sponsored · pin

Mark it as an adCopy Anchor Link

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).
• 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).

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

Reference: hit sponsored · GET /api/v1/insights/campaigns

Add a sponsored productCopy Anchor Link

A sponsored pin is added as any rule is, in a draft that shoppers see nothing of until you publish it.

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'

Pins Vidar Ecksofa mit Schlaffunktion to 1 as a sponsored placement of “Halvard autumn” for searches containing "sofa"

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}'

{"target":"product:SOFA-VIDAR-ECK as a sponsored placement of “Halvard autumn”","placed":1}

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

discarded

Where it standsCopy Anchor Link

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, 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 · rank step

NextCopy Anchor Link

• Rules: conditions, schedules and who wins.
• Insights: the campaign report and its CSV.
• Clicks and views: report a tile's views and clicks.