Variants

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

string

required

The unique identifier of the product

Response

boolean

Whether the request was successful

array

Array of variant category objects

Show variant_category properties

string

Unique identifier for the variant category

string

Name of the variant category (e.g., “Size”, “Color”)

curl https://api.gumroad.com/v2/products/product_id/variant_categories \
  -H "Authorization: Bearer <access_token>"

{
  "success": true,
  "variant_categories": [
    {
      "id": "vc_abc123",
      "title": "Size"
    },
    {
      "id": "vc_def456",
      "title": "Color"
    }
  ]
}

Get Variant Category

Retrieve details for a specific variant category.

GET /v2/products/:product_id/variant_categories/:id

Path Parameters

string

required

The unique identifier of the product

string

required

The unique identifier of the variant category

Response

boolean

Whether the request was successful

object

The variant category object

curl https://api.gumroad.com/v2/products/product_id/variant_categories/vc_abc123 \
  -H "Authorization: Bearer <access_token>"

{
  "success": true,
  "variant_category": {
    "id": "vc_abc123",
    "title": "Size"
  }
}

Create Variant Category

Create a new variant category for a product.

POST /v2/products/:product_id/variant_categories

Path Parameters

string

required

The unique identifier of the product

Body Parameters

string

required

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

Response

boolean

Whether the request was successful

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"

{
  "success": true,
  "variant_category": {
    "id": "vc_abc123",
    "title": "Size"
  }
}

Update Variant Category

Update an existing variant category.

PUT /v2/products/:product_id/variant_categories/:id

Path Parameters

string

required

The unique identifier of the product

string

required

The unique identifier of the variant category

Body Parameters

string

The new name for the variant category

Response

boolean

Whether the request was successful

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"

{
  "success": true,
  "variant_category": {
    "id": "vc_abc123",
    "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

string

required

The unique identifier of the product

string

required

The unique identifier of the variant category

Response

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

{
  "success": true
}

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

string

required

The unique identifier of the product

string

required

The unique identifier of the variant category

Response

boolean

Whether the request was successful

array

Array of variant objects

Show variant properties

string

Unique identifier for the variant

string

Name of the variant (e.g., “Small”, “Red”)

string

Optional description of the variant

integer

Price difference from base product price in cents (can be negative, positive, or zero)

integer

Maximum inventory for this variant (null for unlimited)

curl https://api.gumroad.com/v2/products/product_id/variant_categories/vc_abc123/variants \
  -H "Authorization: Bearer <access_token>"

{
  "success": true,
  "variants": [
    {
      "id": "var_123",
      "name": "Small",
      "description": "Fits US sizes 6-8",
      "price_difference_cents": 0,
      "max_purchase_count": 50
    },
    {
      "id": "var_456",
      "name": "Large",
      "description": "Fits US sizes 12-14",
      "price_difference_cents": 500,
      "max_purchase_count": 30
    }
  ]
}

Get Variant

Retrieve details for a specific variant.

GET /v2/products/:product_id/variant_categories/:variant_category_id/variants/:id

Path Parameters

string

required

The unique identifier of the product

string

required

The unique identifier of the variant category

string

required

The unique identifier of the variant

Response

boolean

Whether the request was successful

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

{
  "success": true,
  "variant": {
    "id": "var_123",
    "name": "Small",
    "description": "Fits US sizes 6-8",
    "price_difference_cents": 0,
    "max_purchase_count": 50
  }
}

Create Variant

Create a new variant within a variant category.

POST /v2/products/:product_id/variant_categories/:variant_category_id/variants

Path Parameters

string

required

The unique identifier of the product

string

required

The unique identifier of the variant category

Body Parameters

string

required

The name of the variant (e.g., “Small”, “Red”, “Digital Edition”)

string

Optional description for the variant

integer

default:"0"

Price difference from the base product price in cents. Can be negative (discount) or positive (premium).

integer

Maximum inventory available for this variant (omit for unlimited)

Response

boolean

Whether the request was successful

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"

{
  "success": true,
  "variant": {
    "id": "var_789",
    "name": "Medium",
    "description": "Fits US sizes 10-12",
    "price_difference_cents": 200,
    "max_purchase_count": 40
  }
}

Update Variant

Update an existing variant.

PUT /v2/products/:product_id/variant_categories/:variant_category_id/variants/:id

Path Parameters

string

required

The unique identifier of the product

string

required

The unique identifier of the variant category

string

required

The unique identifier of the variant

Body Parameters

string

The new name for the variant

string

The new description for the variant

integer

New price difference in cents

integer

New maximum inventory count

Response

boolean

Whether the request was successful

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"

{
  "success": true,
  "variant": {
    "id": "var_123",
    "name": "Small",
    "description": "Fits US sizes 6-8",
    "price_difference_cents": 300,
    "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

string

required

The unique identifier of the product

string

required

The unique identifier of the variant category

string

required

The unique identifier of the variant

Response

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

{
  "success": true
}

Error Codes

Bad Request - Missing required parameters or invalid values

Unauthorized - Invalid or missing access token

Forbidden - Insufficient permissions (requires edit_products scope for create/update/delete)

Not Found - Product, variant category, or variant not found

Unprocessable Entity - Invalid variant parameters (e.g., price difference makes product price invalid)

​Variant Categories

​List Variant Categories

​Path Parameters

​Response

​Get Variant Category

​Path Parameters

​Response

​Create Variant Category

​Path Parameters

​Body Parameters

​Response

​Update Variant Category

​Path Parameters

​Body Parameters

​Response

​Delete Variant Category

​Path Parameters

​Response

​Variants

​List Variants

​Path Parameters

​Response

​Get Variant

​Path Parameters

​Response

​Create Variant

​Path Parameters

​Body Parameters

​Response

​Update Variant

​Path Parameters

​Body Parameters

​Response

​Delete Variant

​Path Parameters

​Response

​Error Codes

Variant Categories

List Variant Categories

Path Parameters

Response

Get Variant Category

Path Parameters

Response

Create Variant Category

Path Parameters

Body Parameters

Response

Update Variant Category

Path Parameters

Body Parameters

Response

Delete Variant Category

Path Parameters

Response

Variants

List Variants

Path Parameters

Response

Get Variant

Path Parameters

Response

Create Variant

Path Parameters

Body Parameters

Response

Update Variant

Path Parameters

Body Parameters

Response

Delete Variant

Path Parameters

Response

Error Codes