---
title: "Set the pinned product order"
method: POST
path: "/api/products/featured"
tags: ["products"]
---

# Set the pinned product order

`POST /api/products/featured`

## Request

- Base URL: `https://api.depixapp.com`
- URL: `https://api.depixapp.com/api/products/featured`
- Auth: HTTP bearer

Reconciles the whole pinned set of the merchant's public page in one call: products in `productIds` are pinned in that order; every other product is unpinned. An empty array clears all pins. Requires scope `merchant_write` on the API-key path.

## Request body

- object: The ordered pinned set.
  - `productIds` string[], required: Ordered product ids to pin (max 50, no duplicates). Empty array clears all pins.

## Response `200`

Pinned set reconciled.

- FeaturedResponse: Result of reconciling the pinned product set.
  - `success` true, required: Always true on success.
  - `featured` string[], required: The pinned product ids in their new display order.

## Other responses

- `400`: productIds is not a valid list (type, duplicates, >50 items).
- `401`: Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.
- `403`: The API key lacks the `merchant_write` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.
- `404`: One or more ids do not belong to this merchant (in the current mode).
- `429`: Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).

---

[API](https://skmtc.dev/depixapp/apis/depix-api.md) · [All operations](https://skmtc.dev/depixapp/apis/depix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/depixapp/apis/depix-api/revisions/04094536dd0f?raw)