Skip to main content
Payouts represent payments from Gumroad to you. The payouts API allows you to retrieve your payout history, view individual payout details, and check upcoming payouts.
The payouts API requires the view_payouts scope. To access sale details within payouts, you also need the view_sales scope.

​
List Payouts

Retrieve a paginated list of your payouts. 
GET /v2/payouts

​
Query Parameters

​
after
string
Filter payouts created after this date (format: YYYY-MM-DD)
​
before
string
Filter payouts created before this date (format: YYYY-MM-DD)
​
page_key
string
Pagination key from the previous response to fetch the next page
​
include_upcoming
boolean
default:"true"
Whether to include upcoming payouts in the first page. Pass "false" to exclude.

​
Response

​
success
boolean
Whether the request was successful
​
payouts
array
Array of payout objects (up to 10 per page)
​
next_page_key
string
Pagination key to fetch the next page (present if more pages exist)
​
next_page_url
string
Full URL to fetch the next page (present if more pages exist)
curl "https://api.gumroad.com/v2/payouts?after=2024-01-01&before=2024-12-31" \
  -H "Authorization: Bearer <access_token>"

​
Get Payout

Retrieve details for a specific payout. 
GET /v2/payouts/:id

​
Path Parameters

​
id
string
required
The unique identifier of the payout

​
Query Parameters

​
include_sales
boolean
default:"true"
Whether to include arrays of sale IDs. Requires view_sales scope. Pass "false" to exclude.
​
include_transactions
boolean
default:"false"
Whether to include detailed transaction breakdown. Pass "true" to include.

​
Response

​
success
boolean
Whether the request was successful
​
payout
object
The payout object
curl https://api.gumroad.com/v2/payouts/payout_abc123 \
  -H "Authorization: Bearer <access_token>"

​
Get Upcoming Payouts

Retrieve information about upcoming payouts that haven’t been processed yet. 
GET /v2/payouts/upcoming

​
Query Parameters

​
include_sales
boolean
default:"true"
Whether to include arrays of sale IDs. Requires view_sales scope. Pass "false" to exclude.
​
include_transactions
boolean
default:"false"
Whether to include detailed transaction breakdown. Pass "true" to include.

​
Response

​
success
boolean
Whether the request was successful
​
payouts
array
Array of upcoming payout objects (id will be null for upcoming payouts)
curl https://api.gumroad.com/v2/payouts/upcoming \
  -H "Authorization: Bearer <access_token>"

​
Payout Statuses

​
creating
Payout is being created
​
processing
Payout is being processed by the payment processor
​
unclaimed
Payout has been sent but not claimed (PayPal only)
​
completed
Payout has been successfully completed
​
failed
Payout failed (funds returned to your balance)
​
cancelled
Payout was cancelled
​
reversed
Payout was reversed (funds returned to your balance)
​
returned
Payout was returned by the bank (funds returned to your balance)

​
Pagination

Payouts are returned 10 at a time. To fetch subsequent pages:
  1. Make an initial request to /v2/payouts
  2. If next_page_key is present in the response, there are more results
  3. Make another request with page_key parameter set to the next_page_key value
  4. Repeat until next_page_key is absent
When using pagination with page_key, upcoming payouts are not included in the results, even if include_upcoming is true.

​
Error Codes

​
400
Bad Request - Invalid date format (dates must be in YYYY-MM-DD format) or invalid page_key
​
401
Unauthorized - Invalid or missing access token
​
403
Forbidden - Insufficient permissions (requires view_payouts scope)
​
404
Not Found - Payout not found

Build docs developers (and LLMs) love

Get started for freeTalk to us