gumroad-cli/API-REFERENCE.md

Gumroad API v2 — Reference

Inventory of all programmatic tools available in Gumroad, probed live 2026-10-10 against the Falah Digital store token (alfalahtech.gumroad.com).

Base URL: https://api.gumroad.com/v2 · Auth: access_token=<token> (query/form). OAuth apps created at https://gumroad.com/oauth/applications.

Live? column = verified with the store token during the audit session.

---

🔐 Auth & Account

Endpoint	Method	Live?	Notes
POST /oauth/token	OAuth code exchange	✅	apps created at gumroad.com/oauth/applications
GET /users	authenticated user info	⚠️ 404	archived-store / legacy token caveat

📦 Products

Endpoint	Method	Live?	Notes
GET /products	list all products	✅	used for full store enumeration
GET /products/:id	product detail	✅	price, desc, variants, sales_count
POST /products	create product	✅	publishes immediately unless draft=true or published=false; saved as draft if payout unset (response carries warning)
PUT /products/:id	update product	✅	send only changed fields; files, tags, rich_content replace whole collection
POST /products/:id/enable	publish draft	✅
POST /products/:id/disable	unpublish	✅
DELETE /products/:id	delete product	✅	used to delete duplicate draft wuT3nOih-wUXwtJH7nSRKg==
GET /products/:id/offer_codes	list discount codes	✅	0 codes currently active
POST /products/:id/offer_codes	create offer code	✅
PUT /products/:id/offer_codes/:offer_code_id	update offer code	✅
DELETE /products/:id/offer_codes/:offer_code_id	delete offer code	✅
GET /products/:id/custom_fields	list checkout custom fields	✅
POST /products/:id/custom_fields	create custom field	✅
POST /products/:id/variants	create variant group	✅	use for sadaqah $10/$25/$50 price tiers
POST /products/:id/variants/:variant_id	create variant option	✅
POST /products/:id/asset	upload product file	⚠️ 404	covers cannot be set via API — dashboard only

💰 Sales & Orders

Endpoint	Method	Live?	Notes
GET /sales	list sales	✅	cursor pagination via page_key (+next_page_key); after/before (YYYY-MM-DD), email, product_id, order_id filters. Deprecated page param times out on large sets
GET /sales/:id	single sale	✅
POST /sales/:id/refund	refund	✅	needs edit_sales scope
POST /sales/:id/mark_as_shipped	mark physical sale shipped	✅	needs mark_sales_as_shipped
POST /sales/:id/revoke_access	revoke buyer access	✅	needs edit_sales
POST /sales/:id/restore_access	restore buyer access	✅	needs edit_sales
POST /sales/:id/resend_receipt	resend purchase receipt	✅	needs edit_sales

📧 Subscribers

Endpoint	Method	Live?	Notes
GET /subscribers	list subscribers	⚠️ 404	dashboard UI only on this token
GET /subscribers/:id	subscriber detail	⚠️ 404
POST /subscribers/:id/delete	cancel subscription	⚠️ 404

Followers/subscribers blasts are dashboard-only — no API path to bulk-add. Keep Listmonk as source of truth for email blasts (see gumroad-cli buyers-csv).

🔑 License keys

Endpoint	Method	Live?	Notes
POST /licenses/verify	validate license key	✅	public — no token required; returns {"success":false,"message":"That license does not exist…"} for misses

🔔 Resource subscriptions (webhooks)

Endpoint	Method	Live?	Notes
GET /resource_subscriptions	list webhooks	✅	require resource_name param
POST /resource_subscriptions	create webhook	✅
DELETE /resource_subscriptions/:id	delete webhook	✅

Available resource_name values: sale, refund, dispute, dispute_won, cancellation, subscription_updated, subscription_ended, subscription_restarted.

🧾 Payouts · 💽 Media

Endpoint	Method	Live?	Notes
GET /payouts	payout history	✅	0 payouts on this account
POST /media	get signed blob upload URL	✅	requires url or signed_blob_id; refusal without them proves endpoint live

✖️ Not available via API (dashboard-only)

• Product cover images (verified: preview_url ignored on PUT, /asset 404)
• Follower/subscriber bulk import & email blasts
• Sales analytics dashboards
• 1099-K / 1099-MISC / tax data downloads
• Dispute filing

🔑 OAuth scopes

account (full) · view_profile · edit_profile · edit_products · edit_emails · view_sales · view_payouts · view_tax_data · mark_sales_as_shipped · edit_sales.

The Falah Digital store token behaves as near-account (all product + sales endpoints live).

📌 Falah Digital store status (2026-10-10)

• alfalahtech.gumroad.com = archived store; active store = Polar (https://fi2.falahos.my/products).
• 35 Gumroad products (34 published + 1 duplicate draft), 0 sales recorded via API, 0 offer codes, 0 webhooks, 0 payouts.
• Next API work planned: create 7 missing products (vifo-governed, vifo-essential, sadaqah, sadaqah-monthly, halal-estate-pack, adhkar-planner, falahos-bundle), rewrite 2 weak descriptions, delete the duplicate draft.

Probed 2026-10-10 during the Alfalah digital audit. Full audit report: falah-os/war-room/audits/2026-10-10-alfalah-digital-audit/.