104 lines
5.6 KiB
Markdown
104 lines
5.6 KiB
Markdown
# 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/`.* |