Skip to main content
Variants allow you to offer different options for a product (like size, color, or tier). Variants are organized into variant categories, and each variant can have a price difference from the base product price.

​
Variant Categories

Variant categories group related variants together (e.g., “Size” or “Color”).

​
List Variant Categories

Retrieve all variant categories for a product. 
GET /v2/products/:product_id/variant_categories

​
Path Parameters

​
product_id
string
required
The unique identifier of the product

​
Response

​
success
boolean
Whether the request was successful
​
variant_categories
array
Array of variant category objects
curl https://api.gumroad.com/v2/products/product_id/variant_categories \
  -H "Authorization: Bearer <access_token>"

​
Get Variant Category

Retrieve details for a specific variant category. 
GET /v2/products/:product_id/variant_categories/:id

​
Path Parameters

​
product_id
string
required
The unique identifier of the product
​
id
string
required
The unique identifier of the variant category

​
Response

​
success
boolean
Whether the request was successful
​
variant_category
object
The variant category object
curl https://api.gumroad.com/v2/products/product_id/variant_categories/vc_abc123 \
  -H "Authorization: Bearer <access_token>"

​
Create Variant Category

Create a new variant category for a product. 
POST /v2/products/:product_id/variant_categories

​
Path Parameters

​
product_id
string
required
The unique identifier of the product

​
Body Parameters

​
title
string
required
The name of the variant category (e.g., “Size”, “Color”, “Edition”)

​
Response

​
success
boolean
Whether the request was successful
​
variant_category
object
The created variant category object
curl -X POST https://api.gumroad.com/v2/products/product_id/variant_categories \
  -H "Authorization: Bearer <access_token>" \
  -d "title=Size"

​
Update Variant Category

Update an existing variant category. 
PUT /v2/products/:product_id/variant_categories/:id

​
Path Parameters

​
product_id
string
required
The unique identifier of the product
​
id
string
required
The unique identifier of the variant category

​
Body Parameters

​
title
string
The new name for the variant category

​
Response

​
success
boolean
Whether the request was successful
​
variant_category
object
The updated variant category object
curl -X PUT https://api.gumroad.com/v2/products/product_id/variant_categories/vc_abc123 \
  -H "Authorization: Bearer <access_token>" \
  -d "title=T-Shirt Size"

​
Delete Variant Category

Delete a variant category and all its variants. 
DELETE /v2/products/:product_id/variant_categories/:id

​
Path Parameters

​
product_id
string
required
The unique identifier of the product
​
id
string
required
The unique identifier of the variant category

​
Response

​
success
boolean
Whether the request was successful
curl -X DELETE https://api.gumroad.com/v2/products/product_id/variant_categories/vc_abc123 \
  -H "Authorization: Bearer <access_token>"

​
Variants

Variants represent individual options within a variant category.

​
List Variants

Retrieve all variants for a variant category. 
GET /v2/products/:product_id/variant_categories/:variant_category_id/variants

​
Path Parameters

​
product_id
string
required
The unique identifier of the product
​
variant_category_id
string
required
The unique identifier of the variant category

​
Response

​
success
boolean
Whether the request was successful
​
variants
array
Array of variant objects
curl https://api.gumroad.com/v2/products/product_id/variant_categories/vc_abc123/variants \
  -H "Authorization: Bearer <access_token>"

​
Get Variant

Retrieve details for a specific variant. 
GET /v2/products/:product_id/variant_categories/:variant_category_id/variants/:id

​
Path Parameters

​
product_id
string
required
The unique identifier of the product
​
variant_category_id
string
required
The unique identifier of the variant category
​
id
string
required
The unique identifier of the variant

​
Response

​
success
boolean
Whether the request was successful
​
variant
object
The variant object
curl https://api.gumroad.com/v2/products/product_id/variant_categories/vc_abc123/variants/var_123 \
  -H "Authorization: Bearer <access_token>"

​
Create Variant

Create a new variant within a variant category. 
POST /v2/products/:product_id/variant_categories/:variant_category_id/variants

​
Path Parameters

​
product_id
string
required
The unique identifier of the product
​
variant_category_id
string
required
The unique identifier of the variant category

​
Body Parameters

​
name
string
required
The name of the variant (e.g., “Small”, “Red”, “Digital Edition”)
​
description
string
Optional description for the variant
​
price_difference_cents
integer
default:"0"
Price difference from the base product price in cents. Can be negative (discount) or positive (premium).
​
max_purchase_count
integer
Maximum inventory available for this variant (omit for unlimited)

​
Response

​
success
boolean
Whether the request was successful
​
variant
object
The created variant object
curl -X POST https://api.gumroad.com/v2/products/product_id/variant_categories/vc_abc123/variants \
  -H "Authorization: Bearer <access_token>" \
  -d "name=Medium" \
  -d "description=Fits US sizes 10-12" \
  -d "price_difference_cents=200" \
  -d "max_purchase_count=40"

​
Update Variant

Update an existing variant. 
PUT /v2/products/:product_id/variant_categories/:variant_category_id/variants/:id

​
Path Parameters

​
product_id
string
required
The unique identifier of the product
​
variant_category_id
string
required
The unique identifier of the variant category
​
id
string
required
The unique identifier of the variant

​
Body Parameters

​
name
string
The new name for the variant
​
description
string
The new description for the variant
​
price_difference_cents
integer
New price difference in cents
​
max_purchase_count
integer
New maximum inventory count

​
Response

​
success
boolean
Whether the request was successful
​
variant
object
The updated variant object
curl -X PUT https://api.gumroad.com/v2/products/product_id/variant_categories/vc_abc123/variants/var_123 \
  -H "Authorization: Bearer <access_token>" \
  -d "price_difference_cents=300" \
  -d "max_purchase_count=25"

​
Delete Variant

Soft delete a variant (marks as deleted but preserves data). 
DELETE /v2/products/:product_id/variant_categories/:variant_category_id/variants/:id

​
Path Parameters

​
product_id
string
required
The unique identifier of the product
​
variant_category_id
string
required
The unique identifier of the variant category
​
id
string
required
The unique identifier of the variant

​
Response

​
success
boolean
Whether the request was successful
curl -X DELETE https://api.gumroad.com/v2/products/product_id/variant_categories/vc_abc123/variants/var_123 \
  -H "Authorization: Bearer <access_token>"

​
Error Codes

​
400
Bad Request - Missing required parameters or invalid values
​
401
Unauthorized - Invalid or missing access token
​
403
Forbidden - Insufficient permissions (requires edit_products scope for create/update/delete)
​
404
Not Found - Product, variant category, or variant not found
​
422
Unprocessable Entity - Invalid variant parameters (e.g., price difference makes product price invalid)

Build docs developers (and LLMs) love

Get started for freeTalk to us