Skip to main content

​
Introduction

The Gumroad API is a RESTful API that allows you to integrate Gumroad’s features into your applications. With the API, you can manage products, retrieve sales data, verify licenses, manage subscriptions, and more.

​
Base URL

All API requests should be made to: 
https://api.gumroad.com
The API is also accessible through https://gumroad.com/api for backward compatibility.

​
API Version

The current API version is v2. All endpoints are prefixed with /v2: 
https://api.gumroad.com/v2/{endpoint}

​
Request Format

The API accepts standard HTTP methods:
  • GET - Retrieve resources
  • POST - Create new resources
  • PUT - Update existing resources
  • DELETE - Delete resources
curl https://api.gumroad.com/v2/user \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Response Format

All API responses are returned in JSON format with a consistent structure:

​
Success Response

{
  "success": true,
  "user": {
    "id": "user_id",
    "email": "[email protected]",
    "name": "Creator Name"
  }
}

​
Error Response

{
  "success": false,
  "message": "The product was not found."
}
The success field will always be true or false to indicate whether the request was successful.

​
Available Endpoints

The Gumroad API provides the following resources:

​
User

  • GET /v2/user - Retrieve authenticated user information

​
Products

  • GET /v2/products - List all products
  • GET /v2/products/:id - Get a specific product
  • POST /v2/products - Create a new product
  • PUT /v2/products/:id - Update a product
  • DELETE /v2/products/:id - Delete a product
  • PUT /v2/products/:id/enable - Enable (publish) a product
  • PUT /v2/products/:id/disable - Disable (unpublish) a product

​
Sales

  • GET /v2/sales - List all sales with pagination
  • GET /v2/sales/:id - Get a specific sale
  • PUT /v2/sales/:id/mark_as_shipped - Mark a sale as shipped
  • PUT /v2/sales/:id/refund - Refund a sale
  • POST /v2/sales/:id/resend_receipt - Resend receipt email

​
Licenses

  • POST /v2/licenses/verify - Verify a license key
  • PUT /v2/licenses/enable - Enable a license
  • PUT /v2/licenses/disable - Disable a license
  • PUT /v2/licenses/rotate - Rotate a license key
  • PUT /v2/licenses/decrement_uses_count - Decrement license usage count

​
Subscribers

  • GET /v2/products/:id/subscribers - List product subscribers
  • GET /v2/subscribers/:id - Get subscriber details

​
Offer Codes

  • GET /v2/products/:id/offer_codes - List offer codes for a product
  • POST /v2/products/:id/offer_codes - Create an offer code
  • GET /v2/products/:id/offer_codes/:code_id - Get offer code details
  • PUT /v2/products/:id/offer_codes/:code_id - Update an offer code
  • DELETE /v2/products/:id/offer_codes/:code_id - Delete an offer code

​
Variants

  • GET /v2/products/:id/variant_categories - List variant categories
  • POST /v2/products/:id/variant_categories - Create a variant category
  • GET /v2/products/:id/variants - List variants
  • POST /v2/products/:id/variant_categories/:category_id/variants - Create a variant

​
Custom Fields

  • GET /v2/products/:id/custom_fields - List custom fields
  • POST /v2/products/:id/custom_fields - Create a custom field
  • PUT /v2/products/:id/custom_fields/:field_id - Update a custom field
  • DELETE /v2/products/:id/custom_fields/:field_id - Delete a custom field

​
Payouts

  • GET /v2/payouts - List payouts
  • GET /v2/payouts/:id - Get payout details
  • GET /v2/payouts/upcoming - Get upcoming payout information

​
Resource Subscriptions (Webhooks)

  • GET /v2/resource_subscriptions - List webhook subscriptions
  • PUT /v2/resource_subscriptions - Create a webhook subscription
  • DELETE /v2/resource_subscriptions/:id - Delete a webhook subscription

​
Pagination

Endpoints that return lists (like sales) support pagination using the page_key parameter: 
curl https://api.gumroad.com/v2/sales \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Pagination Response

{
  "success": true,
  "sales": [...],
  "next_page_key": "2024-01-15T12:30:45.123456-abc123",
  "next_page_url": "/v2/sales?page_key=2024-01-15T12:30:45.123456-abc123"
}
The page parameter is deprecated. Use page_key instead for better performance and reliability.

​
Filtering

Many endpoints support filtering parameters:

​
Sales Filtering

  • after - Filter sales after a date (format: YYYY-MM-DD)
  • before - Filter sales before a date (format: YYYY-MM-DD)
  • email - Filter by customer email
  • product_id - Filter by product ID
  • order_id - Filter by order ID
curl "https://api.gumroad.com/v2/sales?after=2024-01-01&before=2024-12-31" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Rate Limiting

The API implements standard rate limiting. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.
Best practices:
  • Cache responses when possible
  • Use pagination efficiently
  • Implement exponential backoff for retries
  • Use webhooks instead of polling for real-time updates

​
CORS Support

The API supports Cross-Origin Resource Sharing (CORS) for browser-based applications. Valid origins are configured per environment.

​
Error Handling

The API uses standard HTTP status codes:
  • 200 OK - Request successful
  • 400 Bad Request - Invalid request parameters
  • 401 Unauthorized - Missing or invalid authentication
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 422 Unprocessable Entity - Validation error
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error
Always check the success field in the JSON response body, not just the HTTP status code, as some errors may still return 200 with success: false.

​
Next Steps

Authentication

Learn how to authenticate your API requests using OAuth 2.0

Products API

Manage your Gumroad products programmatically

Sales API

Retrieve and manage your sales data

Licenses API

Verify and manage license keys for your products

Build docs developers (and LLMs) love

Get started for freeTalk to us