Merchandising

Merchandising rules let you control how products rank in search results. You can pin products to specific positions, boost or bury them in rankings, or hide them entirely for specific search queries.

Base URL: https://api.hydrajs.dev

Endpoints

Method	Path	Auth	Description
GET	/v1/search/merchandising	Secret	List merchandising rules
POST	/v1/search/merchandising	Secret	Create a merchandising rule
GET	/v1/search/merchandising/{id}	Secret	Get a merchandising rule
PATCH	/v1/search/merchandising/{id}	Secret	Update a merchandising rule
DELETE	/v1/search/merchandising/{id}	Secret	Delete a merchandising rule

---

List merchandising rules

GET /v1/search/merchandising

Returns all merchandising rules for the store.

Query parameters

Parameter	Type	Description
fields	string	Comma-separated fields to return

Request

curl https://api.hydrajs.dev/v1/search/merchandising \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

{
	"data": [
		{
			"id": "mr_abc123def456ghij",
			"name": "Pin Summer Banner",
			"match_query": "summer",
			"match_type": "contains",
			"action": "pin",
			"product_id": "prod_abc123def456ghij",
			"pin_position": 0,
			"score_multiplier": null,
			"priority": 10,
			"is_active": true,
			"created_at": "2026-02-15T09:00:00.000Z",
			"updated_at": "2026-02-15T09:00:00.000Z"
		}
	]
}

---

Create a merchandising rule

POST /v1/search/merchandising

Creates a rule that controls product ranking for matching search queries.

Request body

Field	Type	Required	Default	Description
name	string	Yes	-	Rule name (1-200 chars)
match_query	string	Yes	-	Search query to match (1-200 chars)
match_type	string	No	"contains"	"all", "exact", or "contains"
action	string	Yes	-	"pin", "boost", "bury", or "hide"
product_id	string	Yes	-	Target product ID
pin_position	integer	No	-	Position index for pin action (0-based)
score_multiplier	number	No	-	Ranking multiplier for boost/bury (0.01-100)
priority	integer	No	0	Rule priority when multiple rules match (0-1000)

Actions

Action	Description
pin	Fix the product at a specific position in results
boost	Multiply the product’s relevance score (use score_multiplier)
bury	Reduce the product’s relevance score (use score_multiplier < 1)
hide	Exclude the product from results entirely

Match types

Type	Description
all	Apply to all search queries
exact	Apply only when query matches exactly
contains	Apply when query contains the match string

Request

curl -X POST https://api.hydrajs.dev/v1/search/merchandising \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pin Summer Banner",
    "match_query": "summer",
    "match_type": "contains",
    "action": "pin",
    "product_id": "prod_abc123def456ghij",
    "pin_position": 0,
    "priority": 10
  }'

Response 201

{
	"data": {
		"id": "mr_abc123def456ghij",
		"name": "Pin Summer Banner",
		"match_query": "summer",
		"match_type": "contains",
		"action": "pin",
		"product_id": "prod_abc123def456ghij",
		"pin_position": 0,
		"score_multiplier": null,
		"priority": 10,
		"is_active": true,
		"created_at": "2026-02-15T09:00:00.000Z",
		"updated_at": "2026-02-15T09:00:00.000Z"
	}
}

---

Get a merchandising rule

GET /v1/search/merchandising/{id}

Retrieves a merchandising rule by ID.

Request

curl https://api.hydrajs.dev/v1/search/merchandising/mr_abc123def456ghij \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 200

Returns the merchandising rule object.

---

Update a merchandising rule

PATCH /v1/search/merchandising/{id}

Partially updates a merchandising rule. Only provided fields are modified.

Request body

All fields from Create a merchandising rule are accepted, plus:

Field	Type	Description
is_active	boolean	Enable or disable the rule

Request

curl -X PATCH https://api.hydrajs.dev/v1/search/merchandising/mr_abc123def456ghij \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "boost", "score_multiplier": 3.0}'

Response 200

Returns the updated merchandising rule object.

---

Delete a merchandising rule

DELETE /v1/search/merchandising/{id}

Permanently deletes a merchandising rule. The affected search queries return to default ranking.

Request

curl -X DELETE https://api.hydrajs.dev/v1/search/merchandising/mr_abc123def456ghij \
  -H "Authorization: Bearer sk_live_YOUR_KEY"

Response 204

Empty body.

---

The merchandising rule object

Field	Type	Description
id	string	Unique ID (prefix: mr_)
name	string	Rule name
match_query	string	Search query to match
match_type	string	"all", "exact", or "contains"
action	string	"pin", "boost", "bury", or "hide"
product_id	string	Target product ID
pin_position	integer	Position index for pin action (nullable)
score_multiplier	number	Ranking multiplier for boost/bury (nullable)
priority	integer	Rule priority (higher = more important)
is_active	boolean	Whether the rule is active
created_at	string	ISO 8601 timestamp
updated_at	string	ISO 8601 timestamp