License Services | Comecero Documentation

A license service allows you to configure a script to provide a license or registration code to customers after they purchase your products. You can create a license service for each product or share a single license service across multiple products. Setting up a license service is easy.

A license service can be configured to return a code from a list, or from a script hosted on a remote server. This document primarily considers the scenario where a code will be returned from a remote server. If you wish to provide a code from a list, simply sign into your account and go to Store> License Services, click "Add" and follow the instructions to configure your license service.

Overview

After a customer payment is successfully completed, Comecero will send a message via HTTP or HTTPS POST to a destination you specify. The HTTP request body will contain a license request object (see "Request Payload Sample" section) that includes details about the order, customer and item for which a license or registration code is being requested. You can configure the license request body to be sent in JSON or XML.

When your script receives a license request, it should take the supplied information and generate the details the customer needs to license or register their product and should output the value as the response body. The total length of the license code response must be 4096 characters or less.

The response can contain the following HTML tags for formatting purposes:  , , , , . Any other HTML characters will be stripped from the response.

Your response to the license request should return an HTTP status code between 200 - 299. Any other response status will be interpreted as a processing failure and the license request will be tried again.

The response you provide to the request will be saved with the associated item on the order and will be provided to the customer after the purchase on the receipt page and / or in the email order confirmation, based on your configuration.

Request Failures

If the license service fails to connect to the HTTP location and is either unable to successfully connect, does not receive a response within 30 seconds or receives an HTTP status code outside of 200 - 299, the license service will consider the request to be a failure and will queue the request to be tried again.

The license service will automatically retry to send the the request again using an "exponential backoff" approach, meaning the longer the request continues to fail, the longer it will wait for the next retry. We'll attempt to deliver the message over several days. You can view failed events within your account under Developer> License Requests.

You can manually request an immediate re-send of a failed or successful request from within the control panel or through the API. If you manually retry a previously failed request and it is successful, future retries will be automatically cancelled. If a manual retry is not successful, the retry schedule will continue as previously scheduled.

You can configure an Event Notification to notify you by HTTP or email when a license request fails. This will help you know when your server or script is having a problem and you may need to take action to resolve the problem. It is important that issues are addressed quickly as your customers will be unable to have their orders fulfilled while requests are failing.

If an order has failed license requests, the order confirmation email to the customer will be queued until all license requests have been successfully processed. Immediately upon successful request of all license requests in an order, the order confirmation email will be sent to the customer.

Securing Your Script

There are a few ways you can secure your script from unauthorized access: HTTP basic authentication, custom HTTP headers and request signature.

To secure your script with HTTP basic authentication, simply configure the script to require a username and password by HTTP basic authentication and then supply those values where prompted when creating the license service in the control panel. Every request will contain the credentials you provide, helping ensure that the request is coming from an authorized source.

To secure your script with custom HTTP headers, you can configure your script to only respond to requests that include a custom HTTP header and value that you specify.

You can further verify the authenticity of the request and that it has not been modified by examining the request signature. License requests are signed with an HMAC-SHA256 of the request payload. This value is included in the 'X-Comecero-Signature' HTTP request header when the request is sent to your server and can be used to ensure that the request came from Comecero and has not been modified in transit. The key used to sign the payload is defined in Settings> Technical> Signature Key.

You must not attempt to authenticate the request by using the IP address of the server making the request. Comecero is deployed in a highly-distributed environment and the IP address of the sending server will vary from request to request.

Build Your License Service

The script that processes the license request can be as simple or complex as you need. At a minimum, the script should:

Receive and parse the request payload (JSON or XML) that will be sent by HTTP or HTTPS POST.
Using the supplied data, generate a license or registration code using your algorithm or system.
Return the value you would like provided to the customer as a response.
Provide an HTTP response status code within the range of 200 - 299.

Your response can include basic HTML for formatting. See the "Overview" section for more information.

See the section "Request Payload Sample" at the bottom of this document for an example of the request payload.

You'll notice two important things about the request body:

The request contains a property "product_id" that indicates the product for which the request is being made. If you have the same script that handles requests for multiple products, this will tell you the product for which the request is being made.
The request contains an object "order" which contains the full order details of the customer's order, including an object "customer" that contains the customer data, which you may need to generate the license.

Host Your License Service

Most users choose to host their license service on their own servers. However, you can choose to host it within the Comecero infrastructure if you wish using a Hosted Function.

Configure Your License Service

Once you have built and deployed your license service, you can configure it within the control panel.

From within your account, navigate to Store> License Services and click "Add".
Give the license service a name for your reference, for example "Product A License Code Service"
Provide a label. What do your call your license? A license code, registration code, unlock code, etc. This will be used to describe the code when sent to your customers.
Select "From a remote URL"
Provide the URL to your script. The script can be HTTP or HTTPS.
Provide HTTP authorization and a custom header if you have configured your script to use those values (see Securing your Script for more information).
Select your payload format: JSON or XML. This indicates your preferred format for the request body we send with each request.
Optionally provide any instructions you would like to provide to your customers along with the license. For example, this might be instructions on how to use the provided license.
Provide a description of the license service, which are internal notes for your reference.

Click to add the license service. Once created successfully, navigate to a product under Store> Products that you wish to use the license service. Scroll down and locate the "Add License Service" button and click it. Find the license service and add it to your product. You can assign the license service to as many products you wish.

The next purchase made for your product will make a request to your license service.

Request Payload Sample

The below payload will be sent to your script as the request body via HTTP or HTTPS POST.

{
  "object": "license_request",
  "url": "https://api.comecero.com/api/v1/license_requests/0142130710483Lruow24Z6",
  "license_request_id": "0142130710483Lruow24Z6",
  "date_created": "2017-01-04T00:45:10Z",
  "date_modified": "2017-01-04T00:45:10Z",
  "test": true,
  "account_id": "AA0000",
  "status": "queued",
  "product_id": "1001",
  "license": null,
  "license_service": "https://api.comecero.com/api/v1/license_services/0129056741723Ls5nmtGy7",
  "order": {
    "object": "order",
    "url": "https://api.comecero.com/api/v1/orders/6622-NXKHE-858",
    "order_id": "6622-NXKHE-858",
    "date_created": "2017-01-04T00:45:10Z",
    "date_modified": "2017-01-04T00:45:10Z",
    "test": true,
    "account_id": "AA0000",
    "payment_status": "completed",
    "fulfilled": true,
    "currency": "USD",
    "subtotal": 79.95,
    "subtotal_original": 79.95,
    "shipping": 0.0,
    "shipping_original": 0.0,
    "discount": 0.0,
    "tax": 0.0,
    "tax_original": 0.0,
    "total": 79.95,
    "total_original": 79.95,
    "tax_inclusive": false,
    "discount_on_gross": false,
    "settlement_currency": "USD",
    "settlement_subtotal": 79.95,
    "settlement_subtotal_original": 79.95,
    "settlement_shipping": 0.0,
    "settlement_shipping_original": 0.0,
    "settlement_discount": 0.0,
    "settlement_tax": 0.0,
    "settlement_tax_original": 0.0,
    "settlement_total": 79.95,
    "settlement_total_original": 79.95,
    "customer_ip_address": "63.248.76.212",
    "customer_ip_country": "US",
    "referrer": null,
    "affiliate_id": null,
    "promotion_code": null,
    "items_count": 1,
    "items_quantity": 1,
    "items": [\
      {\
        "object": "order_item",\
        "url": "https://api.comecero.com/api/v1/orders/6622-NXKHE-858/items/1001",\
        "item_id": "1001",\
        "date_created": "2017-01-04T00:45:09Z",\
        "date_modified": "2017-01-04T00:45:09Z",\
        "product_id": "1001",\
        "order_id": "6622-NXKHE-858",\
        "name": "Office Suite Pro",\
        "type": "digital",\
        "quantity": 1,\
        "currency": "USD",\
        "price": 79.95,\
        "price_original": 79.95,\
        "reference_price": null,\
        "reference_currency": null,\
        "subtotal": 79.95,\
        "subtotal_original": 79.95,\
        "discount": 0.0,\
        "tax": 0.0,\
        "tax_original": 0.0,\
        "total": 79.95,\
        "total_original": 79.95,\
        "tax_rate": 0.0,\
        "tax_code": null,\
        "settlement_currency": "USD",\
        "settlement_price": 79.95,\
        "settlement_subtotal": 79.95,\
        "settlement_subtotal_original": 79.95,\
        "settlement_discount": 0.0,\
        "settlement_tax": 0.0,\
        "settlement_tax_original": 0.0,\
        "settlement_total": 79.95,\
        "settlement_total_original": 79.95,\
        "fulfilled": true,\
        "product": "https://api.comecero.com/api/v1/products/1001",\
        "subscription": null,\
        "shipments": "https://api.comecero.com/api/v1/orders/6622-NXKHE-858/items/1001/shipments",\
        "license": null,\
        "license_pending": true,\
        "download": null,\
        "meta": null\
      }\
    ],\
    "shipping_item": null,\
    "customer": {\
      "object": "customer",\
      "url": "https://api.comecero.com/api/v1/customers/0142130616328Cu6Vsk6M4",\
      "customer_id": "0142130616328Cu6Vsk6M4",\
      "date_created": "2017-01-04T00:43:36Z",\
      "date_modified": "2017-01-04T00:45:09Z",\
      "account_id": "AA0000",\
      "test": true,\
      "company_name": null,\
      "name": "Joe Example",\
      "email": "joe@example.com",\
      "phone": null,\
      "billing_address": {\
        "object": "address",\
        "name": "Joe Example",\
        "address_1": null,\
        "address_2": null,\
        "city": null,\
        "state_prov": "NY",\
        "postal_code": "10023",\
        "country": "US",\
        "email": null,\
        "meta": null\
      },\
      "shipping_address": {\
        "object": "address",\
        "name": null,\
        "address_1": null,\
        "address_2": null,\
        "city": null,\
        "state_prov": null,\
        "postal_code": null,\
        "country": "US",\
        "email": null,\
        "meta": null\
      },\
      "username": null,\
      "tax_number": null,\
      "tax_exempt": false,\
      "has_payments": true,\
      "locale": "en-US",\
      "meta": null,\
      "payment_methods": "https://api.comecero.com/api/v1/customers/0142130616328Cu6Vsk6M4/payment_methods",\
      "payments": "https://api.comecero.com/api/v1/customers/0142130616328Cu6Vsk6M4/payments",\
      "refunds": "https://api.comecero.com/api/v1/customers/0142130616328Cu6Vsk6M4/refunds",\
      "orders": "https://api.comecero.com/api/v1/customers/0142130616328Cu6Vsk6M4/orders",\
      "subscriptions": "https://api.comecero.com/api/v1/customers/0142130616328Cu6Vsk6M4/subscriptions",\
      "invoices": "https://api.comecero.com/api/v1/customers/0142130616328Cu6Vsk6M4/invoices"\
    },\
    "cart": "https://api.comecero.com/api/v1/carts/0142130616297CaItI3Jr5",\
    "payment": "https://api.comecero.com/api/v1/payments/0142130709984PyZwyr0YD",\
    "refunds": "https://api.comecero.com/api/v1/orders/6622-NXKHE-858/refunds",\
    "invoice": null,\
    "promotion": null,\
    "shipments": "https://api.comecero.com/api/v1/orders/6622-NXKHE-858/shipments"\
  }\
}

Response Payload Sample

<b>Username:</b> Joe Example<br>
<b>License Code:</b>: IUB2PQYUHAZMUJE4XDVGO6WYQQ4FFN57HFT2IJV9