AppSumo Licensing API (v2)

# Connect to AppSumo

# Receiving webhook requests

Receiving webhook requests from AppSumo requires 4 steps.

  1. Saving your webhook URL (See Webhooks: Getting started)
  2. Validating the request
  3. Processing the webhook request
  4. Return a "success" response

There is also a test webhook request that verifies the webhook saved in the AppSumo Partner Portal (opens new window).

# Validating the request

Anytime a user makes a purchase (or activates/deactivates a license) a webhook is sent to the webhook URL provided. To ensure that the request is valid (and not someone trying to malicious), you will need to authenticate the request (See Webhook security).

# Processing the webhook request

After validating the request, you will need to process the data that is sent to you. The request sent will allow onboarding of new users or deactivating existing ones. What you decide to do with this information is up to you. However, we suggest that you update the status of the license in your system as well, for auditing purposes. For example, if you receive a deactivate event, set the license status for your user's account to deactivated.

Looking for a list of webhook definitions? Check out Webhook Object located at the bottom of this page.

# Purchase events

After a license is purchased, the purchase data will be sent to your webhook. You can use the license_key to set up a placeholder account for the user (so it will be ready when they activate and access your product.)

Example:

{
  "license_key": "3794577c-3dbc-11ec-9bbc-0242ac130002",
  "plan_id": "1510ad397635386dd1ce401ddddde8886cbaa927efa0f3c66de680cfed5b7480",
  "event": "purchase",
  "license_status": "inactive",
  "event_timestamp": 1318781876406,
  "created_at": 1318738512,
  "test": false
}

# Activate events

After a license is activated, the activate data will be sent to your webhook.

Example:

{
  "license_key": "3794577c-3dbc-11ec-9bbc-0242ac130002",
  "plan_id": "1510ad397635386dd1ce401ddddde8886cbaa927efa0f3c66de680cfed5b7480",
  "event": "activate",
  "license_status": "inactive",
  "event_timestamp": 1318781876406,
  "created_at": 1318738512,
  "tier": 1,
  "test": false,
  "extra": {
    "reason": "Purchased by the customer"
  }
}

Notice that the event is activate but the license status is inactive. The reason for this is because AppSumo needs a successful (200) response from your application to activate it on AppSumo. Once activated, the user will be able to access it via AppSumo.

Note: It is the responsibility of the AppSumo Partner to activate the user in their application as well.

# Upgrade events

An upgrade event is sent when customer enhances the license tier of a product.

Example (Upgrade from tier 1 to tier 2):

{
  "license_key": "c86ad3d7-3942-4d11-8814-b0bd81971691",
  "prev_license_key": "3794577c-3dbc-11ec-9bbc-0242ac130002",
  "plan_id": "c0e3375e7f360894ba72a988b43ab9df84f32e90e63c5a268054ae8c7c48a78e",
  "event": "upgrade",
  "event_timestamp": 1671586387628,
  "created_at": 1671586387624,
  "license_status": "inactive",
  "tier": 2,
  "test": false,
  "extra": {
    "reason": "Upgraded by the customer"
  }
}

Each time a license is upgraded, it generates a new and unique license_key UUID. This key will be the customer's current activated license key for your product. The license status will be inactive and you need to activate it on your side. Once you reply with a successful response AppSumo is going to activate it in our side.

The purpose of the new UUID is to provide a better license history and traceability. The prev_license_key and tier properties will allow you to apply the new tier to a customer. A very brief example would be to:

  • Find the customer by their license_key
  • Either:
    • Remove old license key entry and create a new one
    • Replace the license key with the new license key and update the tier.

In addition to the upgrade event, you will receive a simultaneous deactivate event for the previous license for traceability purposes:

{
  "license_key": "3794577c-3dbc-11ec-9bbc-0242ac130002",
  "plan_id": "1510ad397635386dd1ce401ddddde8886cbaa927efa0f3c66de680cfed5b7480",
  "event": "deactivate",
  "event_timestamp": 1671586388077,
  "created_at": 1671586388072,
  "license_status": "deactivated",
  "tier": 1,
  "test": false,
  "extra": {
    "reason": "Upgraded by the customer"
  }
}

Note: The license_status in the payload is deactivated. AppSumo deactivates the license after sending the upgrade event and receives a successful response from the Partner.

# Downgrade events

A downgrade event is sent when customer reduces the license tier. An example would be downgrading tier 2 to tier 1.

Example:

{
  "license_key": "c8e57fa3-ea5b-4c39-a2bf-74f7f51d01b0",
  "prev_license_key": "c86ad3d7-3942-4d11-8814-b0bd81971691",
  "plan_id": "1510ad397635386dd1ce401ddddde8886cbaa927efa0f3c66de680cfed5b7480",
  "event": "downgrade",
  "event_timestamp": 1671586699435,
  "created_at": 1671586699431,
  "license_status": "inactive",
  "tier": 1,
  "test": false,
  "extra": {
    "reason": "Downgraded by the customer"
  }
}

Similarly to upgrade events, each license's downgrade event generates a new and unique inactive license_key UUID. Even if a product is upgraded to tier 2, then downgraded to tier 1 and finally upgraded back again to tier 2, AppSumo will send the new license_key for each upgrade and downgrade.

In addition to the downgrade event, you will receive a simultaneous deactivate event for the previous license for traceability purpose:

{
  "license_key": "c86ad3d7-3942-4d11-8814-b0bd81971691",
  "plan_id": "c0e3375e7f360894ba72a988b43ab9df84f32e90e63c5a268054ae8c7c48a78e",
  "event": "deactivate",
  "event_timestamp": 1671586699927,
  "created_at": 1671586699922,
  "license_status": "deactivated",
  "tier": 2,
  "test": false,
  "extra": {
    "reason": "Downgraded by the customer"
  }
}

# Deactivate events

After a license is deactivated, the deactivate data will be sent to your webhook. A separate, unrelated deactivate event will be triggered by a user requesting a refund or intervention by AppSumo staff.

Example:

{
  "license_key": "c8e57fa3-ea5b-4c39-a2bf-74f7f51d01b0",
  "plan_id": "1510ad397635386dd1ce401ddddde8886cbaa927efa0f3c66de680cfed5b7480",
  "event": "deactivate",
  "license_status": "active",
  "event_timestamp": 1671586699927,
  "created_at": 1671586699922,
  "test": false,
  "extra": {
    "reason": "Refunded by the user"
  }
}

Notice that the event is deactivate but the status is active. The reason for this is because AppSumo needs a successful (200) response from your application to deactivate it on AppSumo. Once deactivated, the user will no longer be able to access it via AppSumo.

Note: It is the responsibility of the AppSumo Partner to deactivate the user in their application as well.

# Test webhook events

Test events are initiated when trying to save a webhook via the AppSumo Partner Portal (opens new window). Notice that the test is true. This means that the data can be ignored, but it must still send a successful (200) response.

Example:

{
  "license_key": "00000000-aaaa-1111-bbbb-abcdef012345",
  "plan_id": "1510ad397635386dd1ce401ddddde8886cbaa927efa0f3c66de680cfed5b7480",
  "event": "purchase",
  "license_status": "inactive",
  "event_timestamp": 1318781876406,
  "created_at": 1318738512,
  "tier": 1,
  "test": true,
  "extra": {
    "reason": "Test event"
  }
}

# Sending a successful response

In order to ensure that the webhook was successfully received, AppSumo needs a confirmation response. All that is needed in the response is to repeat the event back (for event types see above) and with success = true.

Example: 

1

# Webhook Object

# Attributes

license_key string - UUID
The Product's license key the webhook belongs to. This is a UUID string based on RFC 4122 (opens new window)

prev_license_key string
The previous Product's license key. This field is sent only for upgrade or downgrade webhook.

plan_id string
The auto-generated, non-editable, back end source of truth identifier of the AppSumo license tier (tier 1, tier 2, etc). As a partner, tier and plan_id are coupled.

event string
The event is the customer action for the Product's license key, it's one of activate, deactivate, purchase, upgrade, downgrade.

event_timestamp integer - timestamp
Time at which the webhook was sent. It changes when retrying to deliver the webhook.

created_at integer - timestamp
Time at which the license key was created. It does not change on retrying.

license_status string
The current status of the license on AppSumo side.

tier integer
The tier applied for the Product license key.

test boolean
Indicates if it's a test request or not.

extra extra
Metadata information.

# Extra Object

# Attributes

reason string
The reason why the webhook was sent.

← Webhook Security →