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

# Comp Deliver

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

## 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-deliver`
- Auth: API key in header `X-API-Key`

Deliver FREE files (POC samples, design-partner deliverables) via magic links.

Admin-only (same gate as revoke/resend — the read-only key is refused). The
files must already be staged in the exports bucket; each key is HEAD-checked
so a dead link can never be minted. Creates:

  - the `commerce.customer` (find-or-create by email — the ledger continuity),
  - a hidden $0 product (listed=False, like a "Sell this list" ad-hoc product),
  - one Order with status='comp' — never 'pending'/'paid'/'delivered', so the
    stuck-order money scan skips it and no ledger view can count it as revenue,
  - one Export row per file with a durable download token (ADR-026 defaults:
    5-download cap, 30-day window; both overridable here),

then emails the recipient their links with evaluation wording — no price, no
receipt language. Tenet #12 (Show Value Before Asking for Money) + #13
(Eliminate Friction for the Buyer). The links come back in the response too,
so a failed send never strands the delivery.

## Request body

- CompDeliverRequest: Operator comp delivery — free files through the paid-order door (admin-only). POC samples and design-partner deliverables (immediate driver: the iPostal1 evaluation workbooks) get the exact same delivery UX as a purchase: durable magic link, download cap, 30-day window, revoke, per-attempt audit, and a row in the customer ledger — with no payment and no receipt language anywhere.
  - `buyer_email` string, required
  - `buyer_name` string, nullable
  - `buyer_company` string, nullable
  - `label` string, nullable
  - `note` string, nullable
  - `files` CompFile[], required
    - `s3_key` string, required
    - `label` string, nullable
    - `record_count` integer, nullable
  - `expires_days` integer, nullable
  - `download_limit` integer, nullable

## Response `200`

Successful Response

- CompDeliverResponse
  - `order_id` string, required
  - `customer_id` string, required
  - `files` CompDeliveredFile[], required
    - `s3_key` string, required
    - `label` string, nullable, 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)