From a1d9800161468e367e0ef588be4029ec4f795537 Mon Sep 17 00:00:00 2001
From: Wmj Ismail <wmj@falahos.my>
Date: Wed, 23 Sep 2026 22:58:54 +0800
Subject: [PATCH] Document Gumroad file-attachment silent-failure gotcha (from
 Odysseus's findings)

---
 gumroad-file-hosting-gotcha.md | 63 ++++++++++++++++++++++++++++++++++
 1 file changed, 63 insertions(+)
 create mode 100644 gumroad-file-hosting-gotcha.md

diff --git a/gumroad-file-hosting-gotcha.md b/gumroad-file-hosting-gotcha.md
new file mode 100644
index 0000000..81997d7
--- /dev/null
+++ b/gumroad-file-hosting-gotcha.md
@@ -0,0 +1,63 @@
+# Gumroad file-attachment silently fails — always host files yourself
+
+Surfaced 2026-09-23 while building a biweekly "Notion AI generates new
+digital product" routine. Original design had the routine render a PDF
+and upload it directly to a Gumroad product via API. Before shipping that,
+checked Odysseus's own prior findings first — glad we did.
+
+## The bug (discovered by Odysseus, July 2026)
+
+Documented in `~/.hermes/skills/ecommerce/gumroad-cli/references/gumroad-api-quirks.md`:
+
+- `POST/PUT` a Gumroad product with a `file` param (via API or the `gumroad`
+  CLI's `--file` flag) returns a success response (`"Product updated"`,
+  `success: true`).
+- The file is **not actually attached**. `file_info` on the product stays
+  `{}`. Confirmed across 7 products at the time.
+- Setting `custom_delivery_url` has the same silent-failure shape: API
+  accepts the update, the field never persists.
+- Offer codes have an analogous quirk: creating them via
+  `POST /v2/products/{id}/offer_codes` fails with a misleading "missing
+  required parameters" error even with all documented fields present — but
+  the CLI (`gumroad offer-codes create ...`) works every time.
+
+Net effect: an automation that trusts the "success" response and moves on
+will ship a **live, paid product with no working deliverable** — the
+worst kind of failure because nothing in the API response signals it.
+
+## The fix / standing rule
+
+**Never rely on Gumroad to host the deliverable file.** Instead:
+
+1. Host the actual content file (PDF, ZIP, etc.) on infrastructure you
+   control — a Gitea repo raw-file URL, cPanel, WordPress media, etc.
+2. Put the real download link directly and prominently in the Gumroad
+   product's description.
+3. Use Gumroad's API/CLI only for what it's reliably good at: product
+   metadata (name, price, description), cover images, listing
+   verification, and payment/checkout processing.
+4. For offer codes specifically, use the CLI (`gumroad offer-codes
+   create`), not the raw REST endpoint.
+5. After creating a product, verify the delivery link independently
+   (e.g. `curl -I` the hosted file URL for a 200) rather than trusting
+   any Gumroad-side "attached" flag.
+
+## Other quirks worth knowing (same source)
+
+- **Price units differ by interface.** CLI takes dollars
+  (`--price 7.00` = $7.00). API takes cents (`price=700` = $7.00). Using
+  `--price 700` on the CLI creates a **$700** product by mistake.
+- **Bundle linking** (`bundle_product_ids[]`) silently fails via API —
+  must be done through the Gumroad web UI.
+- Products with zero sales don't rank in Gumroad's own search — new
+  listings need seeded early sales/reviews to become discoverable at all.
+
+## Where this came from
+
+Found by searching this machine's Hermes skill library
+(`~/.hermes/skills/ecommerce/gumroad-cli/references/gumroad-api-quirks.md`
+and `~/.hermes/skills/falah/gumroad-content-automation/SKILL.md`) rather
+than re-deriving it from scratch. General lesson: before wiring a new
+automation against a third-party API, check whether an existing agent
+(Odysseus/"Ody" in this case) already hit and documented the sharp edges —
+cheaper than rediscovering them in production with real money on the line.