---
title: "Comp List"
method: POST
path: "/api/v1/commerce/comp-list"
tags: ["commerce", "commerce"]
---

# Comp List

`POST /api/v1/commerce/comp-list`

## Request

- Base URL: `https://app.goodleads.club` (the document declares no server; this is the origin it was published from)
- URL: `https://app.goodleads.club/api/v1/commerce/comp-list`
- Auth: API key in header `X-API-Key`

Build the cohort's workbook and deliver it FREE through the comp door.

Admin-only. Resolves the cohort exactly as a sale would, builds the
customer workbook through the one gated builder, uploads it, and writes the
same ledger rows POST /commerce/comp-deliver writes (customer find-or-create,
hidden $0 product carrying the filter so "Sell this again" works, one Order
with status='comp', one Export with a durable token). Then emails the
recipient with evaluation wording. The Run Manifest records exactly what
shipped (`order.run_manifest_id`), same as a paid order.

Nothing is written if the file can't be built: a gate refusal or an empty
cohort returns 422 and leaves no order behind.

## Request body

- CompListRequest: Operator "Send free" — the Sell modal's comp path. The cohort on screen (filter bar or hand-picked rows, same 1/some/all contract as Sell) becomes a workbook and goes out through the comp door: status='comp', hidden $0 product, durable 30-day link, evaluation wording, no Stripe session. Unlike POST /commerce/comp-deliver there is no staging step — the file is built here from the cohort, so the operator never touches an s3_key.
  - `label` string, required
  - `state` string, nullable
  - `filters` object[]
  - `entity_ids` string[], nullable
  - `lead_count` integer, nullable
  - `audience` string
  - `buyer_email` string, required
  - `buyer_name` string, nullable
  - `note` string, nullable

## Response `200`

Successful Response

- CompListResponse
  - `order_id` string, required
  - `record_count` integer, required
  - `download_url` string, required
  - `expires_at` string, required
  - `email_sent` boolean, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/goodleads/apis/formation-gtm-api.md) · [All operations](https://skmtc.dev/goodleads/apis/formation-gtm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/goodleads/apis/formation-gtm-api/revisions/2068d13a82cf?raw)