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

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.");
    });