Payouts

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

string

Filter payouts created after this date (format: YYYY-MM-DD)

string

Filter payouts created before this date (format: YYYY-MM-DD)

string

Pagination key from the previous response to fetch the next page

boolean

default:"true"

Whether to include upcoming payouts in the first page. Pass "false" to exclude.

Response

boolean

Whether the request was successful

array

Array of payout objects (up to 10 per page)

Show payout properties

string

Unique identifier for the payout (null for upcoming payouts)

string

Payout amount in decimal format (e.g., “1234.56”)

string

Currency code (e.g., “USD”, “EUR”)

string

Payout status: creating, processing, unclaimed, completed, failed, cancelled, reversed, or returned

string

ISO 8601 timestamp of when the payout was created

string

ISO 8601 timestamp of when the payout was completed (null if not completed)

string

Payment processor used (e.g., “stripe”, “paypal”)

string

Last 4 digits of the bank account (e.g., “****1234”)

string

PayPal email address for PayPal payouts

string

Pagination key to fetch the next page (present if more pages exist)

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>"

curl "https://api.gumroad.com/v2/payouts?page_key=eyJjcmVhdGVkX2F0IjoiMjAyNC0wMi0xNVQxMjowMDowMFoiLCJpZCI6MTIzfQ==" \
  -H "Authorization: Bearer <access_token>"

{
  "success": true,
  "payouts": [
    {
      "id": null,
      "amount": "523.45",
      "currency": "USD",
      "status": "processing",
      "created_at": "2024-03-15T00:00:00Z",
      "processed_at": null,
      "payment_processor": "stripe",
      "bank_account_visual": "****1234",
      "paypal_email": null
    },
    {
      "id": "payout_abc123",
      "amount": "1234.56",
      "currency": "USD",
      "status": "completed",
      "created_at": "2024-02-15T00:00:00Z",
      "processed_at": "2024-02-17T14:30:00Z",
      "payment_processor": "stripe",
      "bank_account_visual": "****1234",
      "paypal_email": null
    }
  ],
  "next_page_key": "eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMjowMDowMFoiLCJpZCI6NDU2fQ==",
  "next_page_url": "https://api.gumroad.com/v2/payouts?page_key=eyJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNVQxMjowMDowMFoiLCJpZCI6NDU2fQ=="
}

Get Payout

Retrieve details for a specific payout.

GET /v2/payouts/:id

Path Parameters

string

required

The unique identifier of the payout

Query Parameters

boolean

default:"true"

Whether to include arrays of sale IDs. Requires view_sales scope. Pass "false" to exclude.

boolean

default:"false"

Whether to include detailed transaction breakdown. Pass "true" to include.

Response

boolean

Whether the request was successful

object

The payout object

Show additional fields when include_sales=true

array

Array of sale IDs included in this payout

array

Array of refunded sale IDs that reduced this payout

array

Array of disputed sale IDs that affected this payout

Show additional fields when include_transactions=true

array

Detailed breakdown of all transactions in this payout period

curl https://api.gumroad.com/v2/payouts/payout_abc123 \
  -H "Authorization: Bearer <access_token>"

curl "https://api.gumroad.com/v2/payouts/payout_abc123?include_sales=true" \
  -H "Authorization: Bearer <access_token>"

curl "https://api.gumroad.com/v2/payouts/payout_abc123?include_transactions=true" \
  -H "Authorization: Bearer <access_token>"

{
  "success": true,
  "payout": {
    "id": "payout_abc123",
    "amount": "1234.56",
    "currency": "USD",
    "status": "completed",
    "created_at": "2024-02-15T00:00:00Z",
    "processed_at": "2024-02-17T14:30:00Z",
    "payment_processor": "stripe",
    "bank_account_visual": "****1234",
    "paypal_email": null,
    "sales": ["sale_123", "sale_456", "sale_789"],
    "refunded_sales": ["sale_012"],
    "disputed_sales": []
  }
}

Get Upcoming Payouts

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

GET /v2/payouts/upcoming

Query Parameters

boolean

default:"true"

Whether to include arrays of sale IDs. Requires view_sales scope. Pass "false" to exclude.

boolean

default:"false"

Whether to include detailed transaction breakdown. Pass "true" to include.

Response

boolean

Whether the request was successful

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>"

{
  "success": true,
  "payouts": [
    {
      "id": null,
      "amount": "523.45",
      "currency": "USD",
      "status": "processing",
      "created_at": "2024-03-15T00:00:00Z",
      "processed_at": null,
      "payment_processor": "stripe",
      "bank_account_visual": "****1234",
      "paypal_email": null
    }
  ]
}

Payout Statuses

Payout is being created

Payout is being processed by the payment processor

Payout has been sent but not claimed (PayPal only)

Payout has been successfully completed

Payout failed (funds returned to your balance)

Payout was cancelled

Payout was reversed (funds returned to your balance)

Payout was returned by the bank (funds returned to your balance)

Pagination

Payouts are returned 10 at a time. To fetch subsequent pages:

Make an initial request to /v2/payouts
If next_page_key is present in the response, there are more results
Make another request with page_key parameter set to the next_page_key value
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

Bad Request - Invalid date format (dates must be in YYYY-MM-DD format) or invalid page_key

Unauthorized - Invalid or missing access token

Forbidden - Insufficient permissions (requires view_payouts scope)

Not Found - Payout not found

Getting Started

Products

Sales

Licenses

Subscribers

Other Resources

List Payouts

Query Parameters

Response

Get Payout

Path Parameters

Query Parameters

Response

Get Upcoming Payouts

Query Parameters

Response

Payout Statuses

Error Codes

​List Payouts

​Query Parameters

​Response

​Get Payout

​Path Parameters

​Query Parameters

​Response

​Get Upcoming Payouts

​Query Parameters

​Response

​Payout Statuses

​Pagination

​Error Codes

List Payouts

Query Parameters

Response

Get Payout

Path Parameters

Query Parameters

Response

Get Upcoming Payouts

Query Parameters

Response

Payout Statuses

Pagination

Error Codes