API Documentation

As of version 2.1, the request key has been changed to wc_am_action. See changelog for details.

Postman is recommended for remote API testing.

If you are still using an alphanumeric Software Title for the product_id, it is best practice as of version 2.0 to use the positive integer product_id, especially for variable products to avoid errors. If you are using the WooCommerce API Manager PHP Library for Plugins and Themes to connect to the API Manager on your store, you should update your WordPress plugins and themes to the latest version, since it is optimized for the latest version of the API Manager.

Client software sends a query string in an HTTP(s) request to the API Manager using either POST or GET. The query string contains a series of keys and values.

• wc_am_action (request pre version 2.1) – What action is being requested such as activate, when an API Key is being activated.
• instance – A unique alphanumeric string that is not repeated.
• product_id – A positive integer that corresponds to a real product in the WooCommerce store.
• api_key – A unique alphanumeric string that is not repeated, and is in authenticated requests. There are three types: Master API Key, Product Order API Key, and an Associated API Key.
• plugin_name
  • WordPress Plugin: The lowercase name of the plugin directory, a forward slash, then the name of the root file. For example:  search-engine-ping/search-engine-ping or optionally search-engine-ping/search-engine-ping.php with the .php ending.
  • WordPress Theme: The lowercase name of the theme directory, a forward slash, then the lowercase name of the plugin directory. For example: search-engine-ping/search-engine-ping.
  • Non WordPress Software: Use something with a similar format.
• version – An iterative version of a software release, service, or some other product. Used for WordPress plugin update requests.
• object – Used to identify where the API Key is being activated from. The object could be a server, smart phone, or anything capable of sending an HTTP(s) request.
• slug – The lowercase name of the plugin/theme directory. For example: search-engine-ping.

Note: WordPress plugins and themes require the ‘plugin_name’ and ‘slug’ keys and values depending on the API request, however non WordPress software can send fake data formatted as if it were WordPress software.

An instance ID is generated on the object, such as inside client software or on a device, when it sends the first activate request to activate an API Key to gain access to API Resources. The instance ID is similar to a password, in that it must be unique, and should never be repeated elsewhere. It is okay to save the instance ID on the device, however it is important to understand how it will be used. For example, if a WordPress plugin or theme were being sold, each plugin/theme would create a unique instance ID for each API Key activation. For all other API queries, that same instance ID would be sent. When an API Key is deactivated, which is when a deactivate request is sent to the API, the instance ID could be deleted, and an new instance ID created when the API Key is activated again, or saved to be used when the API Key is activated again.

An instance ID is used for an activation, and for all API requests related to that activation, such as a status request. New activations require a new unique instance ID. An instance ID should only exist from the start of an activation, throughout all API requests using that activation, until that activation is deactivated, and then you could save the instance ID if that object will be activated again later, or delete the instance ID so that a new unique instance ID is created for a new unique activation of the same object. This allows the API Manager to distinctly identify which activation has access to API resources that the API Key activated allows access to.

How you create an instance ID is up to you. In the WooCommerce API Manager PHP Library for Plugins and Themes we use a core WordPress password generator.

The constant WC_AM_TRUSTED_SOURCES is used to restrict access to the APIs by specific IP addresses. These IP addresses can be either IPv4 or IPv6. The format to define the constant is an array as shown below.

define( 'WC_AM_TRUSTED_SOURCES', array( 'ip address 1',  'ip address 2', 'ip address 3' );

Add the constant WC_AM_TRUSTED_SOURCES definition to wp-config.php.

When WC_AM_TRUSTED_SOURCES is defined only those IP addresses in the array list will be allowed to access the APIs, while all other IP addresses will be denied access.

To implement, the remote server is required to add an ip_address query string key with the server’s IP address for the value to the HTTP request sent to the API. If using a load balancer, or some other frontend application, the server must still send an IP address in the WC_AM_TRUSTED_SOURCES list to be authorized for API access. The API Manager will attempt to automatically determine the IP address of the sender to compare to the ip_address value sent in the query string, and will only authorize for API access if both IP addresses match.

The use case for this implementation might be a remote server(s) hosting a membership service that requires an API Key to access services. The product would be hosted on a WooCommerce server with WooCommerce API Manager generating the API Key, and authenticating access via the APIs.

The API Manager listens for API requests at the root URL of the web site. For example the root URL might be https://www.toddlahman.com/. The forward slash at the end of the URL should be taken into account when building the query string so that there is not a double forward slash (//) between the root URL and the query string. The endpoint used to connect to the APIs is wc-api as the key, and the value is wc-am-api, so the query string would start as the following:

https://wc/?wc-api=wc-am-api

At the end of this URL + query string any added keys and values would be added using ampersand (&), so it would look something like this:

https://wc/?wc-api=wc-am-api&key=value

The key and value would be replaced with something like &product_id=19. The ampersand (&) cancontenates the next key=value to the query string.

The next key and value is wc_am_action={value}. Below is a list of values for the wc_am_action key.

Each action, such as activate, deactivate, etc., is an API Endpoint that performs specific actions detailed in sections below.

• wc_am_action=activate
• wc_am_action=deactivate
• wc_am_action=status
• wc_am_action=product_list
• wc_am_action=verify_api_key_is_active
• wc_am_action=information
• wc_am_action=update
• wc_am_action=plugininformation (Deprecated: for legacy use only)
• wc_am_action=pluginupdatecheck (Deprecated: for legacy use only)

To build on the URL + query string we could add a request to activate an API Key such that:

https://wc/?wc-api=wc-am-api&wc_am_action=activate

More would need to be added to the query string to provide all the required information to activate the API Key.

Next is a list of the request values with additional required keys each API endpoint requires, along with other details.

Purpose: To activate an API Key that will then allow access to one or more API resources depending on the API Key type.

Response format: JSON

Required keys: api_key, product_id, instance.

Optional keys: object, version. (These values will be recorded in the database for this activation.)

Example query string:

https://wc/?wc-api=wc-am-api&wc_am_action=activate&instance=p1uOusaNM5ub3&object=dev.toddlahman.com/&product_id=62912&version=1.0&api_key=448567cf667c299bb706df6fe64ed2b44c7d37ba

Note: if the object value is defined as a URL, remote the http:// or https://, since some server security will mangle the entire query string, and break it as a result.

Example JSON success response:

{
    "activated": true,
    "message": "0 out of 4 activations remaining",
    "success": true,
    "data": {
        "unlimited_activations": false,
        "total_activations_purchased": 4,
        "total_activations": 4,
        "activations_remaining": 0
    },
    "api_call_execution_time": "0.057487 seconds"
}

Example JSON error response:

{
    "code": "100",
    "error": "Cannot activate API Key. The API Key has already been activated with the same unique instance ID sent with this request.",
    "success": false,
    "data": {
        "error_code": "100",
        "error": "Cannot activate API Key. The API Key has already been activated with the same unique instance ID sent with this request."
    },
    "api_call_execution_time": "0.027128 seconds"
}

Purpose: To deactivate an API Key so the API Key.

Response format: JSON

Required keys: api_key, product_id, instance.

Example query string:

https://wc/?wc-api=wc-am-api&wc_am_action=deactivate&instance=p1uOusaNM5ub3&product_id=62912&api_key=448567cf667c299bb706df6fe64ed2b44c7d37ba

Example JSON success response:

{
    "deactivated": true,
    "activations_remaining": "1 out of 4 activations remaining",
    "success": true,
    "data": {
        "unlimited_activations": false,
        "total_activations_purchased": 4,
        "total_activations": 3,
        "activations_remaining": 1
    },
    "api_call_execution_time": "0.062482 seconds"
}

Example JSON error response:

{
    "code": "100",
    "error": "The API Key could not be deactivated.",
    "success": false,
    "data": {
        "error_code": "100",
        "error": "The API Key could not be deactivated."
    },
    "api_call_execution_time": "0.023881 seconds"
}

Purpose: Returns the status of an API Key activation. Default data returned for product_id includes total activations purchased, total activations, activations remaining, and if the API Key is activated.

Response format: JSON

Required keys: api_key, product_id, instance.

Optional key: version. (The version will be updated when the HTTP request is received.)

Note: If the return value for status_check is active, or for activated is true, then the time limit has not expired and the API Key is still active. If this is for a subscription, then the subscription is still active. The API Manager verifies the API Key activation should still exists, and deletes it if it should not, due to an expired time limit or inactive subscription, before returning a response.

Example query string:

https://wc/?wc-api=wc-am-api&wc_am_action=status&instance=p1uOusaNM5ub3&product_id=62912&api_key=448567cf667c299bb706df6fe64ed2b44c7d37ba

Example JSON success response:

Product ID: 141198

API Key activated.

{
    "status_check": "active",
    "success": true,
    "data": {
        "unlimited_activations": false,
        "total_activations_purchased": 23,
        "total_activations": 1,
        "activations_remaining": 22,
        "activated": true,
        "api_key_expirations": {
            "non_wc_subs_resources": [
                {
                    "friendly_api_key_expiration_date": "September 29, 2022 5:29 am",
                    "number_of_expiring_activations": "3",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141504",
                    "product_id": "141198"
                },
                {
                    "friendly_api_key_expiration_date": "September 29, 2022 7:07 am",
                    "number_of_expiring_activations": "6",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141507",
                    "product_id": "141198"
                },
                {
                    "friendly_api_key_expiration_date": "October 14, 2022 10:37 am",
                    "number_of_expiring_activations": "5",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141523",
                    "product_id": "141198"
                },
                {
                    "friendly_api_key_expiration_date": "September 25, 2022 4:25 pm",
                    "number_of_expiring_activations": "6",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141501",
                    "product_id": "141198"
                },
                {
                    "friendly_api_key_expiration_date": "October 12, 2022 12:10 pm",
                    "number_of_expiring_activations": "3",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141526",
                    "product_id": "141198"
                }
            ],
            "non_wc_subs_resources_total": 5,
            "wc_subs_resources_total": 0
        }
    },
    "api_call_execution_time": "0.001539 seconds"
}

Product ID: 141198

API Key not activated.

{
    "status_check": "inactive",
    "success": true,
    "data": {
        "unlimited_activations": false,
        "total_activations_purchased": 28,
        "total_activations": 0,
        "activations_remaining": 28,
        "activated": false,
        "api_key_expirations": {
            "non_wc_subs_resources": [
                {
                    "friendly_api_key_expiration_date": "September 29, 2022 5:29 am",
                    "number_of_expiring_activations": "3",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141504",
                    "product_id": "141198"
                },
                {
                    "friendly_api_key_expiration_date": "September 29, 2022 7:07 am",
                    "number_of_expiring_activations": "6",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141507",
                    "product_id": "141198"
                },
                {
                    "friendly_api_key_expiration_date": "October 14, 2022 10:37 am",
                    "number_of_expiring_activations": "5",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141523",
                    "product_id": "141198"
                },
                {
                    "friendly_api_key_expiration_date": "September 25, 2022 4:25 pm",
                    "number_of_expiring_activations": "6",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141501",
                    "product_id": "141198"
                },
                {
                    "friendly_api_key_expiration_date": "October 12, 2022 5:10 am",
                    "number_of_expiring_activations": "4",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141526",
                    "product_id": "141198"
                },
                {
                    "friendly_api_key_expiration_date": "October 15, 2022 12:16 am",
                    "number_of_expiring_activations": "4",
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141535",
                    "product_id": "141198"
                }
            ],
            "non_wc_subs_resources_total": 6,
            "wc_subs_resources_total": 0
        }
    },
    "api_call_execution_time": "0.095696 seconds"
}

Product ID: 32960

API Key not activated.

{
    "status_check": "inactive",
    "success": true,
    "data": {
        "unlimited_activations": false,
        "total_activations_purchased": 7,
        "total_activations": 0,
        "activations_remaining": 7,
        "activated": false,
        "api_key_expirations": {
            "wc_subs_resources": [
                {
                    "friendly_api_key_expiration_date": "Not yet ended",
                    "number_of_expiring_activations": "3",
                    "product_title": "Simple Comments - WooCommerce and WordPress Form Protection",
                    "order_id": "141531",
                    "sub_id": "141532",
                    "product_id": "32960"
                },
                {
                    "friendly_api_key_expiration_date": "Not yet ended",
                    "number_of_expiring_activations": "4",
                    "product_title": "Simple Comments - WooCommerce and WordPress Form Protection",
                    "order_id": "141526",
                    "sub_id": "141528",
                    "product_id": "32960"
                }
            ],
            "non_wc_subs_resources_total": 0,
            "wc_subs_resources_total": 2
        }
    },
    "api_call_execution_time": "0.184801 seconds"
}

Example JSON error response:

{
    "code": "100",
    "error": "No API resources exist.",
    "success": false,
    "data": {
        "error_code": "100",
        "error": "No API resources exist."
    },
    "api_call_execution_time": "0.011719 seconds"
}

Purpose: Returns a unique and ordered list of Product IDs, Product Titles, Order IDs, and Sub IDs if the product is a WooCommerce Subscription.

Response format: JSON

Required keys: api_key, instance. (Although a unique Instance ID is required, it is only used with other elements to uniquely cache the response for one hour, and is not associated with an API Key activation.)

Example query string:

https://wc/?wc-api=wc-am-api&wc_am_action=product_list&api_key=b9dc373c7983cda3897c1502574b1bf929e02a53&instance=p1uOusaNM5ub3

Example JSON success response:

{
    "success": true,
    "data": {
        "product_list": {
            "wc_subs_resources": [
                {
                    "product_title": "Simple Comments - WooCommerce and WordPress Form Protection",
                    "order_id": "141526",
                    "sub_id": "141528",
                    "product_id": "32960"
                },
                {
                    "product_title": "Simple Comments - WooCommerce and WordPress Form Protection",
                    "order_id": "141493",
                    "sub_id": "141494",
                    "product_id": "32961"
                },
                {
                    "product_title": "Simple Comments - WooCommerce and WordPress Form Protection",
                    "order_id": "141512",
                    "sub_id": "141513",
                    "product_id": "32962"
                },
                {
                    "product_title": "Simple Comments - WooCommerce and WordPress Form Protection",
                    "order_id": "141495",
                    "sub_id": "141496",
                    "product_id": "137886"
                },
                {
                    "product_title": "Simple Comments - WooCommerce and WordPress Form Protection",
                    "order_id": "141529",
                    "sub_id": "141530",
                    "product_id": "140516"
                }
            ],
            "non_wc_subs_resources": [
                {
                    "product_title": "Variable Product (no subscription)",
                    "order_id": "141526",
                    "product_id": "141186"
                },
                {
                    "product_title": "Simple Product (no subscription)",
                    "order_id": "141504",
                    "product_id": "141198"
                }
            ],
            "non_wc_subs_resources_total": 2,
            "wc_subs_resources_total": 5
        }
    },
    "api_call_execution_time": "0.00181 seconds"
}

Purpose: Returns success true if the API Key exists and is assigned to an active API Resource.

Response format: JSON

Required keys: api_key.

Example query string:

https://wc/?wc-api=wc-am-api&wc_am_action=verify_api_key_is_active&api_key=b9dc373c7983cda3897c1502574b1bf929e02a53

Example JSON success response:

{
    "success": true,
    "api_call_execution_time": "0.095668 seconds"
}

Example JSON error response:

{
    "code": "100",
    "error": "The API Key is not active or does not exist.",
    "success": false,
    "data": {
        "error_code": "100",
        "error": "The API Key is not active or does not exist."
    },
    "api_call_execution_time": "0.003622 seconds"
}

Purpose: Data returned depends on if the request was authenticated or not.

Response format: JSON

Required keys if authenticating: api_key, product_id, plugin_name, instance, version.

Example query string:

https://wc/?wc-api=wc-am-api&wc_am_action=information&instance=p1uOusaNM5ub3&product_id=62912&version=1.0&api_key=448567cf667c299bb706df6fe64ed2b44c7d37ba&plugin_name=search-engine-ping/search-engine-ping.php

Note: For plugin_name requirements see Description of keys sent in HTTP(s) API requests.

Example JSON success response:

{
    "success": true,
    "data": {
        "package": {
            "product_id": "62912"
        },
        "info": {
            "name": "Search Engine Ping",
            "active_installs": 4,
            "version": "1.4",
            "slug": "search-engine-ping/search-engine-ping.php",
            "author": "Todd Lahman LLC",
            "homepage": "https://wc/shop/search-engine-ping/",
            "requires": "3.5",
            "tested": "4.2",
            "last_updated": "2015-04-21",
            "compatibility": "4.2",
            "sections": {
                "changelog": "<h4>2017.1.9 - Version 1.3.8.4</h4>..."
            }
        }
    },
    "api_call_execution_time": "0.034218 seconds"
}

Example JSON error response:

{
    "code": "100",
    "error": "The product ID 62912222 could not be found in this store.",
    "success": false,
    "data": {
        "error_code": "100",
        "error": "The product ID 62912222 could not be found in this store."
    },
    "api_call_execution_time": "0.001816 seconds"
}

Required keys if not authenticating: product_id, plugin_name.

Example query string:

https://wc/?wc-api=wc-am-api&wc_am_action=information&product_id=62912&plugin_name=search-engine-ping/search-engine-ping.php

Note: For plugin_name requirements see Description of keys sent in HTTP(s) API requests.

Example JSON success response:

{
    "success": true,
    "data": {
        "info": {
            "name": "Search Engine Ping",
            "version": "1.4",
            "slug": "search-engine-ping/search-engine-ping.php",
            "author": "Todd Lahman LLC",
            "homepage": "https://wc/shop/search-engine-ping/",
            "requires": "3.5",
            "tested": "4.2",
            "last_updated": "2015-04-21",
            "compatibility": "4.2",
            "sections": {
                "changelog": "<h4>2017.1.9 - Version 1.3.8.4</h4>..."
            }
        }
    },
    "api_call_execution_time": "0.018425 seconds"
}

Example JSON error response:

{
    "code": "100",
    "error": "The product ID 629122 could not be found in this store.",
    "success": false,
    "data": {
        "error_code": "100",
        "error": "The product ID 629122 could not be found in this store."
    },
    "api_call_execution_time": "0.001346 seconds"
}

Purpose: Returns whether a software update is available. If the request is authenticated with an instance ID, then the URL to the file download is returned.

Response format: JSON

Required keys if authenticating: api_key, product_id, plugin_name, instance, version.

Optional key: slug. (slug is optional, but preferred.)

Example query string:

https://wc/?wc-api=wc-am-api&wc_am_action=update&instance=p1uOusaNM5ub3&product_id=62912&version=1.0&api_key=448567cf667c299bb706df6fe64ed2b44c7d37ba&plugin_name=search-engine-ping/search-engine-ping.php&slug=search-engine-ping

Note: For plugin_name requirements see Description of keys sent in HTTP(s) API requests.

Example JSON success response:

Note: package is the file download URL.

{
    "success": true,
    "data": {
        "package": {
            "product_id": "62912",
            "id": "search-engine-ping-62912",
            "slug": "search-engine-ping",
            "plugin": "search-engine-ping/search-engine-ping.php",
            "new_version": "1.4",
            "url": "https://wc/shop/search-engine-ping/",
            "tested": "4.2",
            "upgrade_notice": "",
            "package": "https://s3.amazonaws.com/..."
        }
    },
    "api_call_execution_time": "0.049395 seconds"
}

Example JSON error response:

{
    "code": "100",
    "error": "The product ID 629122 could not be found in this store.",
    "success": false,
    "data": {
        "error_code": "100",
        "error": "The product ID 629122 could not be found in this store."
    },
    "api_call_execution_time": "0.001345 seconds"
}

Required keys if not authenticating: product_id, plugin_name.

Example query string:

https://wc/?wc-api=wc-am-api&wc_am_action=update&product_id=62912&plugin_name=search-engine-ping/search-engine-ping.php

Note: For plugin_name requirements see Description of keys sent in HTTP(s) API requests.

Example JSON success response:

{
    "success": true,
    "data": {
        "package": {
            "id": "search-engine-ping-62912",
            "slug": "search-engine-ping",
            "plugin": "search-engine-ping/search-engine-ping.php",
            "new_version": "1.4",
            "url": "https://wc/shop/search-engine-ping/",
            "tested": "4.2",
            "upgrade_notice": "",
            "package": ""
        }
    },
    "api_call_execution_time": "0.010199 seconds"
}

Example JSON error response:

{
    "code": "100",
    "error": "The product ID 629122 could not be found in this store.",
    "success": false,
    "data": {
        "error_code": "100",
        "error": "The product ID 629122 could not be found in this store."
    },
    "api_call_execution_time": "0.001348 seconds"
}

Response format: serialized

Same as wc_am_action=information, except the response format is serialized, which is required to work with WordPress plugin and theme update requests that use the pre-2.0 API Manager PHP Library.

Response format: serialized

Same as wc_am_action=update, except the response format is serialized, which is required to work with WordPress plugin and theme update requests that use the pre-2.0 API Manager PHP Library.