How to create and publish a Gumroad product with the API

Step 01: Get an access token

In Gumroad, open Settings, then Advanced, create an application, and generate an access token for your own account. Every call below sends it as access_token. Reading products needs only the read scopes, but the create, update, enable and disable actions check for edit_products (it is the doorkeeper_authorize! :edit_products line in links_controller.rb). Keep the token in an environment file outside the repo; it can delete your store.

Step 02: Create the product as a draft

POST https://api.gumroad.com/v2/products
access_token=...&name=Envelope+Budget&price=500&draft=true

price is in cents. The important part is draft=true (or published=false). When we started in September, a bare POST created the product already published, so our script immediately called PUT /v2/products/:id/disable to hide it until the file was attached. The current code has an explicit draft path (create_as_draft?), which is cleaner: nobody can land on a live product with no file in it.

Step 03: Fill in the listing

PUT https://api.gumroad.com/v2/products/:id
description=<p>...</p>&custom_permalink=envelope-budget&custom_summary=...
&custom_receipt=...&customizable_price=true&tags[]=budget&tags[]=offline app

Fields we set on every product: description (HTML paragraphs), custom_permalink (the URL slug, and the key that makes re-runs safe), custom_summary, custom_receipt, customizable_price for pay what you want, taxonomy_id for the category, and tags[]. Our tags had to be short single phrases, 3 to 19 characters, with no commas; longer ones were rejected, so the script trims them to two words.

Step 04 to 06: Upload the file

The file never passes through Gumroad's API servers. presign hands you storage URLs, you upload the bytes straight to them, and complete stitches the parts together. Gumroad's files_controller.rb sets the rules: parts are 100 MB each, the maximum file is 20 GB (the same as the web uploader), and each presigned URL expires after 900 seconds.

A confession, because it is the useful part: our September script PUT the whole file to every part URL. It worked only because every zip we shipped was well under 100 MB, so there was exactly one part. If your file is bigger, slice it, as in the card above.

Then attach it:

PUT https://api.gumroad.com/v2/products/:id
files[][url]=<file_url from complete>&files[][name]=Envelope Budget

The product's file_info stays empty for a few seconds while Gumroad processes the file. Our script polls GET /v2/products/:id every 5 seconds, up to a minute, and refuses to continue if it never fills in.

Step 07: Covers and a thumbnail

POST https://api.gumroad.com/v2/products/:id/covers     url=https://.../cover-1.png
POST https://api.gumroad.com/v2/products/:id/thumbnail  url=https://.../thumbnail.png

Both take a public image URL, not an upload. Gumroad fetches the image and copies it to its own CDN, so the source can disappear afterwards. We hosted ours in a throwaway public repo for the length of the run and made it private once every product had its images.

Step 08: Enable it

PUT https://api.gumroad.com/v2/products/:id/enable

Only after file_info is filled. Our script asserts that first, then enables, then reads the product back and prints published, the formatted price and the short URL as a final check.