Rotate a License Key

Endpoint

PUT https://api.gumroad.com/v2/licenses/rotate

Generates a new license key for an existing purchase while maintaining all other purchase data. This is useful when a license key has been compromised or shared publicly, and you need to issue a replacement key to the legitimate customer.

This endpoint requires authentication with the edit_products scope.

After rotation, the old license key will no longer work. Make sure to communicate the new key to your customer.

Authentication

This endpoint requires an OAuth access token with the edit_products scope. Include your access token in the request:

?access_token=YOUR_ACCESS_TOKEN

Request Parameters

string

required

Your OAuth access token with edit_products scope

string

required

The current license key to rotate

string

The unique identifier for your product (recommended)

string

The product’s permalink (either unique or custom). Can be used instead of product_id.

Response Fields

boolean

Whether the operation was successful

integer

The current usage count for this license (preserved from the old key)

object

Complete purchase information with the new license key

string

The newly generated license key (this replaces the old one)

Other fields follow the same structure as the verify endpoint

Examples

Rotate a license key

curl -X PUT https://api.gumroad.com/v2/licenses/rotate \
  -d "access_token=YOUR_ACCESS_TOKEN" \
  -d "product_id=your-product-id" \
  -d "license_key=ABCD1234-EFGH5678-IJKL9012-MNOP3456"

import requests

response = requests.put(
    'https://api.gumroad.com/v2/licenses/rotate',
    data={
        'access_token': 'YOUR_ACCESS_TOKEN',
        'product_id': 'your-product-id',
        'license_key': 'ABCD1234-EFGH5678-IJKL9012-MNOP3456'
    }
)

data = response.json()
print(f"New license key: {data['purchase']['license_key']}")

const response = await fetch('https://api.gumroad.com/v2/licenses/rotate', {
  method: 'PUT',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    access_token: 'YOUR_ACCESS_TOKEN',
    product_id: 'your-product-id',
    license_key: 'ABCD1234-EFGH5678-IJKL9012-MNOP3456'
  })
});

const data = await response.json();
console.log(`New license key: ${data.purchase.license_key}`);

Success Response

{
  "success": true,
  "uses": 5,
  "purchase": {
    "id": "encrypted_purchase_id",
    "product_name": "My Software",
    "product_id": "encrypted_product_id",
    "product_permalink": "https://gumroad.com/l/my-software",
    "short_product_id": "my-software",
    "email": "customer@example.com",
    "price": 2999,
    "currency": "usd",
    "quantity": 1,
    "created_at": "2024-01-15T10:30:00Z",
    "sale_timestamp": "2024-01-15T10:30:00Z",
    "order_number": 123456,
    "license_key": "WXYZ9876-STUV5432-PQRS1098-NMLK6543",
    "variants": "",
    "custom_fields": [],
    "refunded": false,
    "chargebacked": false,
    "subscription_ended_at": null,
    "subscription_cancelled_at": null,
    "subscription_failed_at": null,
    "can_contact": true
  }
}

Error Responses

Unauthorized (401)

{
  "error": "The access token is invalid"
}

Forbidden (403)

Returned when the access token doesn’t have the edit_products scope.

{
  "error": "Forbidden"
}

Not Found (404)

Returned when the license doesn’t exist or doesn’t belong to your product.

{
  "success": false,
  "message": "That license does not exist for the provided product."
}

Common Use Cases

Respond to Compromised Keys

If a customer’s license key is shared publicly (e.g., on social media or piracy sites), you can rotate it to invalidate the old key and provide them with a new one.

Customer Support

When a customer reports unauthorized use of their license, you can rotate the key as part of your resolution process. This ensures the unauthorized user loses access while the legitimate customer gets a working key.

Security Best Practices

Some organizations require periodic key rotation as a security measure. This endpoint makes it easy to implement such policies.

Implementation Example

import requests

class LicenseSecurityManager:
    def __init__(self, access_token, product_id):
        self.access_token = access_token
        self.product_id = product_id
        self.base_url = 'https://api.gumroad.com/v2/licenses'
    
    def handle_compromised_license(self, old_license_key, customer_email):
        """Rotate a compromised license and notify the customer"""
        
        # First, disable the old key immediately
        requests.put(
            f'{self.base_url}/disable',
            data={
                'access_token': self.access_token,
                'product_id': self.product_id,
                'license_key': old_license_key
            }
        )
        
        # Then rotate to get a new key
        response = requests.put(
            f'{self.base_url}/rotate',
            data={
                'access_token': self.access_token,
                'product_id': self.product_id,
                'license_key': old_license_key
            }
        )
        
        if response.ok:
            data = response.json()
            new_key = data['purchase']['license_key']
            
            # Send the new key to your customer
            self.send_new_license_email(customer_email, new_key)
            
            return new_key
        else:
            raise Exception(f"Failed to rotate license: {response.text}")
    
    def send_new_license_email(self, email, new_key):
        # Your email sending logic here
        pass

The new license key is automatically generated using a secure random algorithm. You cannot specify a custom key format.

Only the product owner can rotate licenses for their products. You must authenticate with an access token from the product owner’s account.

License Key Format

Generated license keys follow the format: XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX

32 hexadecimal characters (0-9, A-F)
Divided into 4 groups of 8 characters
Separated by hyphens
Always uppercase

Getting Started

Products

Sales

Licenses

Subscribers

Other Resources

Rotate a License Key

Endpoint

Authentication

Request Parameters

Response Fields

Examples

Rotate a license key

Success Response

Error Responses

Unauthorized (401)

Forbidden (403)

Not Found (404)

Common Use Cases

Respond to Compromised Keys

Customer Support

Security Best Practices

Implementation Example

License Key Format

​Endpoint

​Authentication

​Request Parameters

​Response Fields

​Examples

​Rotate a license key

​Success Response

​Error Responses

​Unauthorized (401)

​Forbidden (403)

​Not Found (404)

​Common Use Cases

​Respond to Compromised Keys

​Customer Support

​Security Best Practices

​Implementation Example

​License Key Format

Endpoint

Authentication

Request Parameters

Response Fields

Examples

Rotate a license key

Success Response

Error Responses

Unauthorized (401)

Forbidden (403)

Not Found (404)

Common Use Cases

Respond to Compromised Keys

Customer Support

Security Best Practices

Implementation Example

License Key Format