Cruxo

Cruxo is a retail-media platform. Register a Cruxo account as a sponsored-products provider with "platform": "cruxo" in config, and the rest of config is read against Cruxo’s contract.

Cruxo names its parameters differently per account, so most of this config records the names your account uses. Your Cruxo contact supplies every value here.

config options

Field	Required	Default	Meaning
platform	Yes	—	"cruxo"
base_url	Yes	—	Base URL of your Cruxo endpoint
service_path	Yes	—	The path segment Cruxo serves this account on
domain	Yes	—	The domain Cruxo knows this storefront by
area	Yes	—	The Cruxo area this account serves, such as search
size	Yes	—	Cruxo’s format name for this account, such as product. A name, not a count.
product_id_path	Yes	—	Where the product id sits in a Cruxo response entry, as key||key
position_path	No	none	Where a position sits in a response entry, same form. Omit it and no positions are read — see Positions.
aliases	No	{}	Cruxo’s names for the request parameters, as standard name → your account's name
use_page	No	true	Whether the page number is sent along with the request
test	No	none	Cruxo’s test flag. Set it and the traffic is marked non-billable.
change_item_url	No	false	Whether a sponsored hit’s URL is replaced with the click-tracking URL Cruxo returns

A complete registration:

curl -X POST 'https://api.eu1.luigisbox.ai/platform/v1/sponsored-providers' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "organization_id": "lbo_r2vn8c",
    "name": "Cruxo — example.com search",
    "config": {
      "platform": "cruxo",
      "base_url": "https://ads.example-cruxo.io",
      "service_path": "retail",
      "domain": "example.com",
      "area": "search",
      "size": "product",
      "product_id_path": "ad||productId",
      "position_path": "ad||position",
      "aliases": { "site": "outpost", "cdomain": "cdom", "size": "fmt" }
    }
  }'

Cruxo does not authenticate its callers, so a Cruxo provider is normally registered without credentials.

Aliases

aliases accepts site, cdomain, viewId, random, layout, size, keyword and mid.

A renamed parameter is sent only if you name it. site, cdomain, viewId, random, layout and size are omitted from the request entirely when they are absent from aliases — so a Cruxo account that expects site under its own name gets no domain at all until that entry is there. keyword and mid are always sent, under their alias when you give one and under their standard name otherwise.

Positions

position_path decides whether Cruxo’s own positions are used. With it, they are honoured. Without it, positions are not read, no fixed-position pinning happens, and sponsored results are only promoted within ranking.

A promoted result is placed at the position Cruxo returns for it, counted within the page being served: position 3 on the second page is the third result of that page. Without position_path, or when Cruxo returns a position for only some of the promoted results, they take the first slots of the page in the order Cruxo returned them.

Promotion only moves results already on the page; none is added or removed. A promoted result is not placed when:

• its position is beyond the last result on the page,
• another promoted result or a fixed-position placement already holds that slot,
• the result is itself a fixed-position placement,
• on the first page, a campaign pin holds that slot or placed that result.

A result that is not placed keeps its order among the other unplaced results, but can shift as promotions are placed around it, and carries no Cruxo @disclosure. On later pages, promotions take precedence over campaign pins.

A placement’s max_placements_pin above 0 does nothing unless position_path is set.

See also

• Sponsored products — providers, placements, and the caps
• Business rules — how a sponsored decision resolves against your own rules