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

**<color>Live?</color>** 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/`.*