1. Home
  2. Docs
  3. WooCommerce License Keys
  4. Developers
  5. Customize API

Customize API

WooCommerce License Keys has the ability to customize the data received (in the request) and returned (in the responses) via WordPress hooks.

This lets the API extend its functionality to meet a certain business requirement.


Customize API Request

The request is seen as a collection of data sent to the API to be processed. A $request variable is created before processing the request, on each endpoint, and the request data is captured and stored in it.

The API provides 3 filter hooks (one for each endpoint) to allow customization to the data that is captured by the request. These hooks are called after the API has captured essential request data.

Hooks

woocommerce_license_keys_activate_request
woocommerce_license_keys_validate_request
woocommerce_license_keys_deactivate_request

Parameters

$request
array
This is the default data stored inside the array:

$request[‘store_code’]
string
Store code.

$request[‘sku’]
string
Product SKU.

$request[‘key_code’]
string
Customer’s license key code.

$request[‘domain’]
string
Domain name (optional). Default: localhost (default value can be changed using filter hook woocommerce_license_key_default_domain).

$request[‘ip’]
string
IP address.

$request[‘license_key’]
object | LicenseKeys\Models\LicenseKey
License Key model object. NOTE: This is only available and loaded into $request after certain validations have been met.

$request[‘activation_id’]
int
Activation ID. NOTE: Only available for validation and deactivation endpoints.

Returns

Filter expects array $request to be returned back.

Code Sample

The intention in the following example is capture a customer’s email address to add an extra layer of security by, not only validating matching license key, but validating that the email matches the one used to make the purchase. The sample will expect the email information to be sent in the “customer_email” request parameter and will use class WPMVC\Request, as utility, to obtain the value.

add_filter( 'woocommerce_license_keys_activate_request', function( $request ) {

    // Here we capture the "customer_email" sent in the request.
    $request['customer_email'] = \WPMVC\Request::input( 'customer_email' );

    return $request;

} );

We recommend to add sanitation functions like sanitize_text_field(), intval() or floatval() to prevent injections.


Customize API Request Before Validation

The hook above will allow you to add more HTTP request values, but it is triggered before the license key details are loaded. You might want to load additional data to the request, related to the license key before it is validated, to do this, use these hooks instead:

woocommerce_license_keys_activate_request_preval
woocommerce_license_keys_validate_request_preval
woocommerce_license_keys_deactivate_request_preval

Parameters

$request
array
Request data sent and captured in the request. Read Customize API Request for more information.

$response
object|WPMVC\Response
The response (object class) that will be returned, it is expected to be returned back by any hook. The returned information is stored at property: $response->data (array)

Returns

Filter expects array $request to be returned back.

Code Sample

The intention in the following example is to add a membership data class to the request based on the license key obtained, this class will be later used to make validations and or to append extra information to the response.

add_filter( 'woocommerce_license_keys_activate_request_preval', function( $request, $response ) {

    $order = wc_get_order( $request['license_key']->order_id );

    // We load into the request the membership class data.
    $request['membership'] = new Membership( $order->get_customer_id() );

    return $request;

}, 10, 2 );

Add Custom Validation

The API provides 3 filter hooks (one for each endpoint) to allow customization to the response, by adding additional validations and errors. These hooks are called before the request is approved and the data is returned in the response.

Hooks

woocommerce_license_keys_activate_response
woocommerce_license_keys_validate_response
woocommerce_license_keys_validate_response

Parameters

$response
object|WPMVC\Response
The response (object class) that will be returned, it is expected to be returned back by any hook. The returned information is stored at property: $response->data (array)

$request
array
Request data sent and captured in the request. Read Customize API Request for more information.

$args
array
Validation arguments (Can be customized using filter hook woocommerce_license_keys_validation_args). This contains additional arguments to be considered during validation, for example the error output format.

Returns

Filter expects parameter $response (WPMVC\Response) to be returned back.

Code Sample

The intention in the following example is to validate the customer email address sent in the sample used in section “Customize API Request“.

Notices how first we evaluate the arguments to detect how is the output formatted. This will dictate how should we associate our errors when present.

Then we apply simple logic to the $request data to make our validations possible. We first validate if the email address captured by the request is not empty and then we validate its validity, by matching it with the order related to the license key.

add_filter( 'woocommerce_license_keys_activate_response', function( $response, $request, $args ) {

    // First we init a bool variable that will indicate us
    // if the output format is using error codes
    $is_code = isset( $args['error_format'] ) && $args['error_format'] === 'code';

    // First custom validation will verify that the email address is required.
    if ( empty( $request['customer_email'] ) ) {
        $response->error( ( $is_code ? 1000 : 'customer_email' ), __( 'Required.' ) );
        return $response;
    }

    // Second custom validation will verify that the email matches.
    // -- Get woocommerce order
    $order = wc_get_order( $request['license_key']->order_id );
    if ( $request['customer_email'] !== $order->get_billing_email() ) {
        $response->error( ( $is_code ? 1001 : 'customer_email' ), __( 'Invalid email.' ) );
        return $response;
    }

    return $response;

}, 10, 3 );

In order to prevent compatibility with future plugin releases, we recommend to use custom error codes above 1000.


Customize API Response

The API provides 3 filter hooks (one for each endpoint) to allow customization to the data that will be returned in the response. These hooks are called after request has been processed and validated.

Hooks

woocommerce_license_keys_activate_success_response
woocommerce_license_keys_validate_success_response
woocommerce_license_keys_deactivate_success_response

Parameters

$response
object|WPMVC\Response
The response (object class) that will be returned, it is expected to be returned back by any hook. The returned information is stored at property: $response->data (array)

$request
array
An array with all the data captured in the request. Read Customize API Request for more information.

Returns

Filter expects parameter $response (WPMVC\Response) to be returned back.

Code Sample

The intention in the following example is to add customer’s data in the returning response.

add_filter( 'woocommerce_license_keys_activate_success_response', 'response_with_customer_order_data', 10, 2 );
add_filter( 'woocommerce_license_keys_validate_success_response', 'response_with_customer_order_data', 10, 2 );

/**
 * Filters the response and returns it with additional customer / order data.
 *
 * @link https://docs.woocommerce.com/wc-apidocs/class-WC_Order.html
 *
 * @param object $response
 * @param array  $request
 *
 * @return object $response should be returned back.
 */
function response_with_customer_order_data( $response, $request ) {
    
    // Get woocommerce order
    $order = wc_get_order( $request['license_key']->order_id );
    
    // Get customer information
    $response->data['customer'] = [
        'id'        => $order->get_customer_id(),
        'email'     => $order->get_billing_email(),
        'firstname' => $order->get_billing_first_name(),
        'lastname'  => $order->get_billing_last_name(),
    ];
    
    return $response;
}
Was this article helpful to you? Yes No