agent-playbooks/gumroad-file-hosting-gotcha.md

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.