License keys

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
• Managing licenses and subscriptions
  • What happens when a customer cancels a subscription or their payment fails?
• 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

License keys can be enabled and embedded directly from the product's content page. Go to your product's content page, click on the three-dot menu item, and select 'License key'.

You can drag and reposition the license key module anywhere on the page, but it can only be added to any one page of your content.

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.

Expand the License key module on your content page and toggle on "Allow customers to choose number of seats per license purchased"

If you'd like to prepopulate the number of seats for a given customer, you can use the quantity URL parameter (Example: https://hypermatic.gumroad.com/l/emailify?layout=profile&quantity=4)

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 increases. However, for a decrease in seats, their membership will get updated at the end of the current billing cycle. After that, they will be charged the reduced amount starting from the next renewal.

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 your “verify” license API calls. Gumroad performs no additional license key verification.

Remember that checking for a valid license on each launch 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, get this by expanding the license key module on the content 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  }}

You will receive a 404 response code with an error message if verification fails.

Managing licenses and subscriptions

Our Licenses API will continue to return the key state as enabled until you disable it; however, we set the following fields with the appropriate timestamps so you can know if and when the membership has ended:

1. subscription_ended_at
2. subscription_cancelled_at
3. subscription_failed_at

So if one of these fields is not null, you can disable the license and terminate access to the software.

What happens when a customer cancels a subscription or their payment fails?

1. subscription_ended_at
2. subscription_cancelled_at
3. subscription_failed_at

Please note that all these timestamps correspond to the membership end date and not the cancellation requested date/time. Also, successfully renewing or restarting the membership will reverse the values of these fields back to "null."

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.
• Why is “purchaser_id" missing from the returned payload? We store and return a `purchaser_id` only when the purchase is made by a signed-in user. As you might be aware, it is not necessary to be logged in to Gumroad to make a purchase, and thus not every purchase might have a `purchaser_id` linked with it. When the purchase is made by a signed-in user, we store that user’s ID as the purchaser_id otherwise, it is nil. If it’s present, we respond with purchaser_id in the API, otherwise, we don’t even include the purchaser_id key in the response. (ref)
• Can I create products or upload content with the API? Sorry, that's not yet possible. While we’re not working on this at the moment, you can add this to our feature request page (and also vote on others). Our Product team regularly checks this list while planning future releases.