# 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.