---
title: "Exclude a creator from GMV Max"
method: POST
path: "/gmv-max/excluded-creators"
tags: ["GMV Max"]
---

# Exclude a creator from GMV Max

`POST /gmv-max/excluded-creators`

Manually exclude a creator (by TikTok `handle`) from this shop's GMV Max bottom-of-funnel delivery. Idempotent on (shop, handle): re-excluding an already-excluded creator is a no-op upsert that returns the existing row. Requires `read_write` scope and an `Idempotency-Key`. Single shop only.

## Headers

- `Idempotency-Key` string, nullable

## Request body

- GmvMaxExcludeCreatorRequest — POST /gmv-max/excluded-creators request body — manually exclude a creator from the shop's GMV Max delivery. Idempotent on (shop, handle): re-excluding an already-excluded creator is a no-op upsert.
  - `handle` string, required — The creator's TikTok handle to exclude from GMV Max delivery — the same `handle` returned by GET /gmv-max/excluded-creators. Excludes the creator's videos from the shop's bottom-of-funnel ad boosts.

## Response `200`

Successful Response

- GmvMaxExcludeCreatorWriteResponse — POST /gmv-max/excluded-creators — echoes the excluded creator row.
  - `data` GmvMaxExcludedCreatorItem, required — One creator excluded from the shop's GMV Max bottom-of-funnel delivery. Mirrors the portal's `BofExcludedCreatorItem` shape 1:1 so the public read is byte-identical to what the in-app GMV Max screen shows.
    - `handle` string, required — The creator's TikTok handle.
    - `source` string, required — How the exclusion was created: `manual` (via POST /gmv-max/excluded-creators or the portal) or `auto_bof` (the reconcile job's automatic bottom-of-funnel detection).
    - `reason` string, nullable — Why the creator was flagged (populated for `auto_bof` rows).
    - `bof_confidence` integer, nullable — Auto-detection confidence 0–100 (populated for `auto_bof` rows).
    - `excluded_video_count` integer — How many of the creator's videos this exclusion covers.
    - `applied_status` string, required — Whether the exclusion has taken effect on spend: `applied` (live), `pending` (armed, reconcile job hasn't run yet), or `failed`.
    - `decided_by` string, nullable — Who created the exclusion. For public-API writes this is the calling API key's identity (`api_key:<prefix>`).
    - `created_at` string, date-time, nullable — When the exclusion row was first created.
    - `updated_at` string, date-time, nullable — When the reconcile job last touched this row.

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `409` — Conflict
- `422` — Unprocessable Entity
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) · [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/reacherapp/reacher-data-api/revisions/3ea20a9f734b/schema)