Sample License Add-on

See Selling - License to download an example add-on that includes a PHP library to communicate with the SugarOutfitters API via cURL.

Overview

To keep things as simple as possible we currently offer an HTTP API which returns JSON.

Feedback

Although we aim to keep things simple sometimes it is just too simple. If you can"t find what you need or require additional functionality let us know by submitting a feature request or by contacting us.

Validate License Key

Request

GET https://www.sugaroutfitters.com/api/v1/key/validate?public_key=xxxxxxx&key=xxxxxx

Request Arguments

public_key (required) The add-on plan"s public key.

NOTE: If you want to have a single installable package that supports multiple plans, simply pass a comma separated list of the public keys from each plan. For example: GET https://www.sugaroutfitters.com/api/v1/key/validate?public_key=publickey1,publickey2,publickey3&key=xxxxxx

key (required) The purchaser"s license key user_count (optional) The number of users currently active in the purchaser"s install. The SampleLicenseAddon.zip counts all "Active" users towards this number. It is up to the add-on to decide how to count users. For example, you may want to exclude group users. Or if you are doing a marketing-type add-on, you may wish to only count marketing users.

Response

Success HTTP Status Code = 200 Body contains response Error HTTP Status Code = 400 Body contains error string

Example Request

GET https://www.sugaroutfitters.com/api/v1/key/validate?public_key=xxxxxxxxxxxxx&key=xxxxxxxxxxx

Example Response

{"validated":true}

Example User Count Validation Request

GET https://www.sugaroutfitters.com/api/v1/key/validate?public_key=xxxxxxxxxxxxx&key=xxxxxxxxxxx&user_count=10

Example Response

{"validated":true,"user_count":"10","licensed_user_count":"1","validated_users":false}

Possible Response Messages

Success "Key is valid and active." - When all is good!

Errors

• "Key is required." - Missing license key on API call
• "Public Key is required." - Missing public key on API call
• "User Count must be an integer." - User Count is not a valid integer, must be greater than 0
• "Public Key does not exist." - The public key does not exist in our system
• "Key does not exist." - The license key does not exist in our system
• "Key is inactive." - The key has been marked as inactive by SugarOutfitters. This may happen if their is license key abuse or something is just not right on our side.
• "Key is suspended by seller." - When the seller suspends a key, this is the message the key will return.
• "Free Trial has expired and payment failed. Update payment information on SugarOutfitters to continue usage." - When a customer"s free trial expires and their initial payment failed
• "Free Trial was cancelled. Please purchase a new license on SugarOutfitters to continue usage." - When a customer has cancelled a free trial
• "Payment was refunded. Please purchase a new license on SugarOutfitters to continue usage." - When a payment was refunded
• "Subscription was cancelled. Please purchase a new license on SugarOutfitters to continue usage." - When a subscription was cancelled
• "Subscription has expired and payment failed. Update payment information on SugarOutfitters to continue usage." - When a subscription has expired and their payment failed

Update User Count

If your add-on requires a user count for billing you can update the user count on behalf of a purchaser using the API if the user count validation fails. It is best practice to allow the purchaser to trigger the newly updated user count. Upon submission the new count will be applied to the next billing cycle and the purchaser will be notified of the change.

Request

POST https://www.sugaroutfitters.com/api/v1/key/change
Content-Type: application/x-www-form-urlencoded

Request Arguments

public_key (required) The add-on group"s public key key (required) The purchaser"s license key user_count (required) The number of users currently active in the purchaser"s install or greater. The SampleLicenseAddon.zip counts all "Active" users towards this number. It is up to the add-on to decide how to count users.

Response

Success HTTP Status Code = 200 Body contains response Error HTTP Status Code = 400 Body contains error string

Example Request

POST https://www.sugaroutfitters.com/api/v1/key/change
Content-Type: application/x-www-form-urlencoded
Body: public_key=xxxxxxxxxxxxx&key=xxxxxxxxxxx&user_count=10

Example Response

{"success":true,"licensed_user_count":"10"}

Code Samples

jQuery

If you are using PHP use cURL if possible as it handles cross domain requests more easily. If you must use jQuery jsonp is really the only option. The biggest limitation with jsonp is that it doesn"t do error handling so we must use a timeout to trigger the error handler manually. If you wish to be able to get the true error response then look into this jsonp plugin.

Validation using jsonp Note the format param in the data object.

    $.ajax("https://www.sugaroutfitters.com/api/v1/key/validate", {
        type: "GET",
        dataType: "jsonp",
        crossDomain: true,
        data: { format: "jsonp",public_key: "xxxxxxxxxxxxx",key: "xxxxxxxxxxxxx"},
        timeout: 5000 //work around for jsonp not returning errors
    })
    .success(function(response) {
        alert("validated: "+response.validated);
    })
    .error(function() {
        alert("Validation Error: invalid or inactive key.");
    });