License keys

⚠️ Important: Our license key verification API now requires the product_id parameter instead of product_permalink for all products created on or after Jan 9, 2023.

In this article:

• What are license keys for?
• Setting up a product with license keys
  
  • Issuing multi-seat licenses
• How license key enforcement works
• Verifying a license key in your application
  
  • cURL example
  • API response example
• FAQs

What are license keys for? 

License keys are primarily used by creators selling software. License keys can help creators verify purchases through their application, and authorize or revoke access to the software they have created.

License keys will NOT help you limit access to digital audio, video, or ebook files that you are selling on Gumroad.

Setting up a product with license keys

Scroll down to the “Settings” section of your product’s edit page, click the “Generate a unique license key per sale” toggle, and save your changes.You can also retroactively add license keys to a product.

Issuing multi-seat licenses

The “Multi-seat license” setting allows you to issue multiple seats for a single purchase or license key. This feature is currently only available for Membership products.

You will be able to view and manage the number of seats linked with a license key from the customer’s drawer in the Audience dashboard, while your customers can do this from their “Manage membership” page.

Customers will immediately be charged a prorated amount if the number of seats is increased. However, for a decrease in the number of seats, their membership will get updated at the end of the current billing cycle and they will be charged the reduced amount from the subsequent renewals.

For such purchases, the is_multiseat_license field will be set to true in our API response, and the value of quantity will indicate the number of seats.

How license key enforcement works

License key enforcement is completely up to the creator. You can decide how many uses each key gets depending on the “verify” license API calls you make. Gumroad performs no additional license key verification.

Remember that if you check for a valid license on each launch you will increment the usage count unless you set the “increment_uses_count” flag to false. You can also check if a purchase has been refunded or disputed by checking the refunded/disputed fields of the API call response.

Verifying a license key in your application

Use these parameters to verify a license key:

• product_id (the unique ID of the product, available on product's edit page)
• license_key (the license key provided by your customer)
• increment_uses_count ("true"/"false", optional, default: "true")

cURL example

curl https://api.gumroad.com/v2/licenses/verify \
  -d "product_id=SDGgCnivv6gTTHfVRfUBxQ==" \
  -d "license_key=YOUR_CUSTOMERS_LICENSE_KEY" \
  -X POST

API response example

If the verification is successful, you will receive a response similar to this:

{
  "success": true,
  "uses": 3,
  "purchase": {
    "seller_id": "kL0psVL2admJSYRNs-OCMg==",
    "product_id": "32-nPAicqbLj8B_WswVlMw==",
    "product_name": "licenses demo product",
    "permalink": "QMGY",
    "product_permalink": "https://sahil.gumroad.com/l/pencil",
    "email": "customer@example.com",
    "price": 0,
    "gumroad_fee": 0,
    "currency": "usd",
    "quantity": 1,
    "discover_fee_charged": false,
    "can_contact": true,
    "referrer": "direct",
    "card": {
      "expiry_month": null,
      "expiry_year": null,
      "type": null,
      "visual": null
    },
    "order_number": 524459935,
    "sale_id": "FO8TXN-dbxYaBdahG97Y-Q==",
    "sale_timestamp": "2021-01-05T19:38:56Z",
    "purchaser_id": "5550321502811",
    "subscription_id": "GDzW4_aBdQc-o7Gbjng7lw==",
    "variants": "",
    "license_key": "85DB562A-C11D4B06-A2335A6B-8C079166",
    "is_multiseat_license": false,
    "ip_country": "United States",
    "recurrence": "monthly",
    "is_gift_receiver_purchase": false,
    "refunded": false,
    "disputed": false,
    "dispute_won": false,
    "id": "FO8TXN-dvaYbBbahG97a-Q==",
    "created_at": "2021-01-05T19:38:56Z",
    "custom_fields": [],
    "chargebacked": false, # purchase was refunded, non-subscription product only
    "subscription_ended_at": null, # subscription was ended, subscription product only
    "subscription_cancelled_at": null, # subscription was cancelled, subscription product only
    "subscription_failed_at": null # we were unable to charge the subscriber's card
  }
}

If verification fails, you will receive a 404 response code with an error message.

FAQs

• Can I make API calls from the browser?
  Yes, you can send API requests to api.gumroad.com from the browser.
• Does the value of sale_timestamp and created_at update when a subscription is renewed?
  No. They both remain the same as the original value.
• Does the "disable" method cancel the customer’s subscription?
  No, it just disables the license key. Here’s how to cancel a subscription for a customer.
• Can I use my own license keys?
  You either have to choose the license keys we generate or manage your license keys outside of our system. We do not have a way for you to import license keys.
• Can I reset the uses count parameter to zero?
  You can increment or decrement the uses count, but you cannot reset it directly to zero. If you do not wish to increment the uses count at all, there's an increment_uses_count flag in the verify API call that you can set to false. Refer to our API docs here.
• Can I generate license keys for past purchases that did not have a license attached to them originally?
  Yes. When you turn on the "Generate a unique license key per sale" setting, all previous purchases of that product will also get a license key. Your customers will be able to access the key from their respective download pages.