Decrement License Uses

Endpoint

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

Decrements the usage counter for a license key by 1. This is useful when you need to undo a previous verification or when a customer deactivates your software on a device. The counter will not go below 0.

This endpoint requires authentication with the edit_products scope.

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 license key whose usage count should be decremented

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 updated usage count for this license (after decrementing)

object

Complete purchase information associated with this license (same structure as the verify endpoint)

Examples

Decrement license usage count

curl -X PUT https://api.gumroad.com/v2/licenses/decrement_uses_count \
  -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/decrement_uses_count',
    data={
        'access_token': 'YOUR_ACCESS_TOKEN',
        'product_id': 'your-product-id',
        'license_key': 'ABCD1234-EFGH5678-IJKL9012-MNOP3456'
    }
)

print(response.json())

const response = await fetch('https://api.gumroad.com/v2/licenses/decrement_uses_count', {
  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(data);

Success Response

{
  "success": true,
  "uses": 4,
  "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": "ABCD1234-EFGH5678-IJKL9012-MNOP3456",
    "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

Software Deactivation

When a customer deactivates your software on a device, you can decrement the usage counter to free up an activation slot. This is especially useful for licenses that limit the number of simultaneous activations.

Undo Accidental Verification

If your system accidentally verified a license multiple times (e.g., due to a bug or network retry), you can decrement the counter to correct the usage count.

Testing and Development

During development and testing, you may need to decrement usage counts to reset test licenses to their original state.

The usage counter will not go below 0. If the current count is already 0, calling this endpoint will succeed but the count will remain at 0.

Only the product owner can decrement license usage counts for their products. You must authenticate with an access token from the product owner’s account.

Implementation Example

class LicenseManager:
    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 deactivate_device(self, license_key):
        """Deactivate a device and free up an activation slot"""
        response = requests.put(
            f'{self.base_url}/decrement_uses_count',
            data={
                'access_token': self.access_token,
                'product_id': self.product_id,
                'license_key': license_key
            }
        )
        
        if response.ok:
            data = response.json()
            print(f"Device deactivated. Remaining uses: {data['uses']}")
            return True
        else:
            print(f"Failed to deactivate: {response.text}")
            return False

Getting Started

Products

Sales

Licenses

Subscribers

Other Resources

Decrement License Uses

Endpoint

Authentication

Request Parameters

Response Fields

Examples

Decrement license usage count

Success Response

Error Responses

Unauthorized (401)

Forbidden (403)

Not Found (404)

Common Use Cases

Software Deactivation

Undo Accidental Verification

Testing and Development

Implementation Example

​Endpoint

​Authentication

​Request Parameters

​Response Fields

​Examples

​Decrement license usage count

​Success Response

​Error Responses

​Unauthorized (401)

​Forbidden (403)

​Not Found (404)

​Common Use Cases

​Software Deactivation

​Undo Accidental Verification

​Testing and Development

​Implementation Example

Endpoint

Authentication

Request Parameters

Response Fields

Examples

Decrement license usage count

Success Response

Error Responses

Unauthorized (401)

Forbidden (403)

Not Found (404)

Common Use Cases

Software Deactivation

Undo Accidental Verification

Testing and Development

Implementation Example