WooCommerce API Manager

WooCommerce API Manager Requirements ↑ Back to top

Version 2.0.12 Requirements ↑ Back to top

  • PHP 7.0 or greater
  • WooCommerce 3.4 or greater. It is best to have updated WooCommerce within the past year to avoid breaking changes. See changelog for latest changes.
  • If WooCommerce Subscriptions is installed it must be version 2.3 or greater.
  • When upgrading from API Manager pre 2.0 to 2.0 or greater, the data is migrated to custom database tables and the old data is deleted. There is no ability to rollback, or downgrade, to the older version. Test first, backup, and be prepared before upgrading.
  • WordPress requirements (same as the version of WooCommerce installed)
  • OpenSSL should be kept up-to-date.
  • An HTTPS connection to your store is highly recommended.
  • The AUTH_KEY and NONCE_SALT constants that should exist in wp-config.php are used by the API Manager for advanced encryption. If these constants are absent go to https://api.wordpress.org/secret-key/1.1/salt/ and add those keys to wp-config.php.
  • In wp-config.php define( WP_DEBUG’, false ); If debug displays errors on a live production site it will break API requests.
  • Do not cache query strings, since query strings are used in API requests, and must always be unique, not cached copies of previous requests or the API requests will break.
  • Be careful with firewalls, since they can break API requests.
  • DO NOT DELETE PRODUCTS if the API checkbox has been selected. Once a product has been selected to be used as an API product, that product ID will become the product_id (an integer) used by the API Manager to identify that product going forward. Deleting the product will break all client API requests for that product.
  • If a product is duplicated, make sure the API information is unique to the newly created product.

PHP Library

An API Manager drop-in PHP Library is maintained by the developer in a private GitHub repository to help WordPress plugin and theme authors quickly set up products that can communicate with the API Manager APIs. Contact the developer with a Github username, so the username can be added to the repository. If you have more than one developer that need access to the repo, send their Github usernames. The usernames added to the repo are periodically deleted and readded by request to insure the list is up-to-date.

Questions & Support ↑ Back to top

Already purchased and need some assistance? Fill out this support form via the Help Desk.

Have a question before you buy? Please fill out this pre-sales form.

WooCommerce API Manager Versioning ↑ Back to top

The API Manager uses Semantic Versioning, as outlined below:

Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.

A Major version would be 1.0.0 to 2.0.0. A Minor version would be 1.1.0 to 1.2.0. A Patch would be 1.1.0 to 1.1.1. This versioning approach was adopted by WooCommerce in early 2017 as explained in this post.

Updating to a New Version ↑ Back to top

If you’ve already read the section above on WooCommerce API Manager Versioning then you’ll know what a Major version is. When a version goes from something like 1.5.4 to 2.0 that is a Major version, and it means there are breaking changes, so testing is highly recommended, if not required, before applying that update to a live site. WooCommerce has recommendations on how to go about preparing for a Major, or even a Minor, update to make sure your site doesn’t break, or have unexpected behavior. The number one rule to remember is to ALWAYS BACKUP your website before updating to a Major or Minor version.

Settings ↑ Back to top

Accounts & Privacy ↑ Back to top

Found under WooCommerce > Settings > Accounts & Privacy > Guest checkout

API Manager products must be purchased by customers with an existing account, or an account that is created at the time of purchase, so the customer account can be assigned a User ID, which is a critical property in secure authentication through the API to your store. If a customer purchases a product with a guest account the API Manager will fail for that purchased API Resource. Make sure under the Guest Check section that the “Allow customers to place orders without an account” checkbox is unchecked as shown in the screenshot above. To make it easier for new customers it is recommended to check the checkbox for “Allow customers to create an account during checkout” under the Account creation section.

API Manager tab ↑ Back to top

Found under WooCommerce > Settings > API Manager tab.

Amazon S3

The setting allows for file downloads from Amazon S3. The API Manager provides Access Key ID and Secret Access Key form fields on the settings screen, and the Secret Access Key is encrypted when saved in the database, however it is much more secure to define the constants below, and add them to the wp-config.php file.

define('WC_AM_AWS3_ACCESS_KEY_ID', 'your_access_key');
define('WC_AM_AWS3_SECRET_ACCESS_KEY', 'your_secret_key');

Download Links

URL Expire Time: Download URLs on the My Account dashboard, and for software updates, can be set to expire between 5 and 60 minutes after they are created. Each download URL is created on request, and expires to prevent download abuse on sites other than yours. Due to this security, download URLs are not sent in emails after software product purchase.

Save to Dropbox App Key: This creates a Save to Dropbox link in the My Account > My API Downloads section where customers can save their download directly to their Dropbox account.

API Doc Tabs

These tabs are displayed for the WordPress plugin information screen. If the product has a download it is considered software, and if it is a WordPress plugin, these tabs can be optionally displayed, although the changelog tab is required.

API Keys

Product Order API Keys: The default API Keys template always displays the Master API Key, and can hide the Product Order API Keys if you want clients to use only the single Master API Key to activate API resources.

API Response

Send API Resource Data: More detailed information about the product can be sent if this option is on, although it is not required.

Debug

There are several different options available to debug APIs in the API Manager. When this option is selected all information is recorded in log files that can be found under WooCommerce > Status > Logs. The output in the log is beautifully formatted for readability. For additional troubleshooting of areas of code not covered by the default options, the test_log() method in the /includes/wc-am-log.php file can be used. The test log syntax would be similar to the following line of code, where $resources is the variable storing the information to be displayed in the log:

WC_AM_Log()->test_log( PHP_EOL . esc_html__( 'Details from get_resources() method.', 'woocommerce-api-manager' ) . PHP_EOL . wc_print_r( $resources, true ) );

Postman is recommended for remote API testing.

Amazon S3 ↑ Back to top

The API Manager allows an Amazon S3 (Simple Storage Service) URL to be copied and pasted into a product’s Downloadable files > File URL form field, so files can be download through Amazon S3. The secure URLs created by the API Manager for Amazon S3 will expire between 5 – 60 minutes after creation, just like a local download URL, depending on your setting. The WooCommerce > Settings > API Manager screen has form fields for the Amazon S3 keys will be creating, and the secret key is strongly encrypted, however it is much more secure to put the keys in wp-config.php using the defined constants detailed in the Settings section above.

To get started with Amazon Web Services (AWS) login or create an account, then go to the Identity and Access Management (IAM) dashboard. Click on the Continue to Security Credentials button, then click on Users. The objective will be to create a user who has restricted read-only access to Amazon S3 buckets, and no other Amazon services. This helps avoid using root keys that have access to all services connected with the AWS account. The screenshots below will walk through the steps to setup a new restricted user.

Download the .csv file, and store it somewhere secure, because this file contains the Access Key ID, and Secret Access Key you will need to add to wp-config.php using the defined constants (strongly recommended), or to save in the API Manager settings. Step 4, the success screen, will be the only time you can download the .csv file, or to view the Secret Access Key from the Amazon IAM dashboard for this user.

There are different ways to setup restricted users, and Amazon has a lot of documentation in this regard, but the overall objective is better security by limiting access to specific resources.

Now that an IAM user has been created with limited Amazon S3 access it is time to go to Amazon S3 and create a bucket to hold the files that will be downloaded. Once at the Amazon S3 dashboard click the Create bucket button, and follow the screenshot steps below.

  • Note: The IAM user do not have to match the Bucket name, as the Bucket and IAM user are unrelated, although the names do match in the example screenshots only because it made it easier to see which Amazon S3 Bucket was used for the specific IAM user.

On step 3 of the create bucket wizard the screenshot above was displayed, then 6 hours later the screenshot below was displayed, but either way accept the default settings as there are no changes needed.

On step 4 of the create bucket wizard the screenshot above was displayed, then 6 hours later the screenshot below was displayed, but either way accept the default settings as there are no changes needed.

After the bucket is created, click on the bucket and follow the screenshots below to upload a file.

In the previous example the file is a zip file, so the Content-Type was set to application/zip. Once created click on the file to make additional changes needed. The root account is given full access to the file.

Currently the root account has complete permission to access the bucket and files, but no one else does, not even customers, so we need to give the IAM user bucket level permission.

Open the Identity and Access Management (IAM) dashboard, click on Users, then click on the new IAM user you created, then copy the User ARN, and save it for the next step.

Open the Amazon S3 dashboard, select the new bucket > Permissions > Bucket Policy. Towards the bottom of this page click the Policy generator link.

Select the S3 Bucket Policy from the pull-down menu, which should automatically select the Amazon S3 for the AWS Service in the form. Paste the User ARN into the Principal field. In the Actions pull-down menu, select only GetObject, then paste arn:aws:s3:::your-bukcket-name/* into the Amazon Resource Name (ARN) field. Now click Add Statement, then Generate Policy, and copy the resulting code snippet.

Now click Save at the top right of the screen. The code snippet below is a working copy of the code needed.

{
    "Version": "2012-10-17",
    "Id": "Policy1546757468384",
    "Statement": [
        {
            "Sid": "Stmt1546757465773",
            "Effect": "Allow",
            "Principal": {
                "AWS": "arn:aws:iam::592794580436:user/am-test-bucket-1"
            },
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::am-test-bucket-1/*"
        }
    ]
}

The Principal is the User ARN, and the Resource is the bucket name prefixed with arn:aws:s3::: and postfixed with /*. The forward slash is the delimiter, and the asterisk means anything below the bucket level, including all files.

The IAM user name am-test-bucket-1, which is the same name we gave the bucket, now has read access to any files placed in this bucket. Click on Overview and select the file that was uploaded.

Copy the Amazon S3 (Simple Storage Service) URL and paste it into a product’s Downloadable files > File URL form field, so files can be download through Amazon S3.

More than one file can be added to the same Amazon S3 bucket to keep them organized in the same place. Remember to keep the same file name or the Link will have to be changed in the product.

Whenever a product file is download from Amazon S3 through the API Manager now, the download request will be authenticated through the IAM user permissions.

Here’s a summary of how this will all work:

The API Manager will create a secure URL that acts as a wrapper around the Amazon S3 link. The URL is created when the My Account > API Downloads page loads, and it expires in 5 – 60 minutes depending on your setting. The URL is also created when client software sends an API query requesting a software update. The API Manager finds the URL in the product, and sends a reply URL wrapper. This URL has details required by Amazon S3 to authenticate the download request using the IAM user account information created to limit access to read-only Amazon S3, the file being requested, and an expiration time. The Access Key ID and Secret Access Key created, and entered into the API Manager settings or wp-config.php file, are encrypted and sent in the URL wrapper to download the file, so Amazon S3 know the limits of access for the request, and authenticates the request based on this information.

Going forward, the simplest way to manage new file releases is to keep the name the same, and replace the old file with the new file in the same Amazon S3 bucket, so the Link will remain unchanged.

If new Amazon S3 buckets are needed, follow the directions here, then copy and past the bucket policy code snippet, and modify the User ARN and bucket name as needed.

Save to Dropbox ↑ Back to top

After setting the Dropbox App Key in the API Manager settings, a Save to Dropbox button will appear on the API Downloads page in the My Account dashboard. This allows customers to easily save the API Resource directly into their Dropbox account.

There is a link to create the Dropbox app key following the Save to Dropbox App Key setting on the API Manager settings screen. The first step, once this link is followed, is to choose Drop-ins app.

An App key will be available on the next screen. For this to work however, the store domain must be added to Drop-ins domains, and the settings under the Details tab must be set as well.

Account Endpoints ↑ Back to top

Found under WooCommerce > Settings > Advanced > Account Endpoints.

The api-keys and api-downloads are the slug portion of the URL leading to those pages under the My Account dashboard. These values can be changed, or left empty.

To change the API Keys and API Downloads titles, as they appear in the My Account dashboard, use the woocommerce_account_menu_items filter.

Endpoints Not Displayed in My Account Dashboard ↑ Back to top

If the endpoints above are not displayed in the My Account dashboard go to Settings > Permalinks and save twice to flush the rewrite rules, so these new endpoints are included.

Product Setup ↑ Back to top

What is an API product? An API product is referred to as a an API resource, or more simply resource. The API Manager allows access to an API resource through an authentication process, which means clients must be logged in to access their resources, and to purchase API products. All API products are virtual, and can be sold as a service, software, or whatever the product represents in the virtual space. The product can be a WooCommerce Subscription, which is fully supported.

A product can be of type Simple, Simple Subscription, Variable, Variable Subscription, and Grouped. When setting up a Grouped product, the parent product in the group will not have the option to make it an API product, but the products in the group will if they are Simple or Variable products, including WooCommerce Subscription products. External/Affiliate products are placeholder products that link to an external product, and therefore cannot be API products.

To make any of the above products an API product select the API checkbox, and save the changes. Once the API checkbox is checked, it cannot be unchecked, and the product cannot be deleted from the store. There are also Virtual and Downloadable checkboxes, neither of which are required, and only serve to hide or display those options on the product screen to setup the product as needed.

Existing products that have been purchased before the API Manager was installed will have Product Order API Keys created when the API checkbox is selected and the product is updated.

If the product is Downloadable there are several options.

  1. The first is to upload a file on the local server. If this file is a WordPress plugin/theme then it needs to be a .zip file. At the moment, there should only be one download file on the product, with any future uploads replacing the previous, because the API Manager will find the most recent upload for downloads and software updates. These URLs are secure, will be generated on demand, and will expire depending on your setting, but will exist no longer than 60 minutes.
  2. The second option is to use an Amazon S3 URL, which requires further setup for the API Manager to create the Amazon S3 secure URLs. These URLs are secure, will be generated on demand, and will expire depending on your setting, but will exist no longer than 60 minutes.
  3. The last option is to provide an remote URL to file in another location.

Download limits and download expiration will no longer be honored. As of version 2.0 there are only subscription time limits used to limit API access.

API Access Expires ↑ Back to top

The API Access Expires option sets a time limit for an API Resource, which is the product purchased. If the value is left empty, the time limit is indefinite. A number (positive integer) sets a number of days to limit access to the API Resource, so 365 would be a limit of one year. After API access expires the product must be manually purchased again. There is no auto renewal after access expires, and currently no automated emails are sent to notify the customer access will be expiring.

The API Access Expires form field only displays on the Simple product API tab form, and on the variation API form for a Variable product, but not on the Variable product parent API tab form.

The API Access Expires form field will not be displayed on the Simple Subscription and Variable Subscription products created by the WooCommerce Subscription plugin, because those products will already have a subscription time limit set.

Simple/Simple Subscription ↑ Back to top

The following form fields are found on the Product > Product edit screen > API tab.

(Deprecated – Do Not Use) Software Title: This field was used prior to API Manager version 2.0. The value cannot be updated from API tab form. This value will still work if used by client software prior to version 2.0. Going forward only use the Product ID. This field should be empty if the product was created after version 2.0, or for first-time installations of version 2.0.

Product ID: This unique ID cannot be changed, or the client will no longer have access to the product data. The product ID matches the actual product ID.

Activation Limit: (Default is one activation if left blank) The APIs will only allow this number of activations to access this API resource. Activation is accomplished through the authentication of an API Key. Unlimited activations must have a value set, such as 1000. Do not leave this field blank. All resources are limited. Allowing a truly unlimited number of activations would consume an unknown amount of resources, and could cripple the server performance. Setting a reasonable limit will prevent downtime.

Note: If the Activation Limit is increased after the product has been purchased, all API resources for this product will have the Activation Limit raised to the new value. The API resources for this product will not have the Activation Limit lowered if it is decreased.

The remaining fields are specifically used for WordPress plugins/themes, however this data can be used with any client application.

Version: The currently available software version in the store.

Page URL: For WordPress plugins this is the plugin homepage. For WordPress themes, this is the View Version x.x.x Details page. For other software this can be whatever you want it to be.

Author: The software author.

WP Version Required: The version of WordPress required for the plugin/theme to run without errors. Not required for non WordPress software.

WP Version Tested Up To: Highest version of WordPress software was tested on. Not required for non WordPress software.

Last Updated: When the software was last updated.

Upgrade Notice: A notice displayed when an update is available.

The remaining fields are docs derived from WordPress pages that are all optional except for the Changelog. Once a page/doc is selected, an Edit link appears.

Variable/Variable Subscription ↑ Back to top

There are several differences with the API tab on a Variable type product. Referer to the Simple product setup for a description of all other form fields.

  1. The activation field is absent, as it is displayed on each variation product.
  2. The Product ID displayed on the API tab is for the parent product only, and is not used in the client software.
  3. All other data entered in the parent product API tab is copied into the corresponding fields for each variation to make data entry easier across multiple variations.

When multiple pricing options are needed for the same product, a variable product is currently the only viable option.

Variable Product Variations

Once the number of variation products has been created, and the Variable product has been updated with the API tab on the parent product filled out, each variation product will have the same form fields populated, except for the Activation Limit. Creating variations allows different numbers of API Key activations to be sold per product, such as 1, 5, and 25 API Key activations using 3 variations each with 1, 5, and 25 set for the Activation Limit value respectively.

It is possible to set unique values in the variation form fields by checking the “Set API options for this variable product only.” checkbox. If all the product details, other than the number of API Key activations should be the same, don’t check the “Set API options for this variable product only.” checkbox. Below is what the form looks like when setting unique values for a variation, which has already been populated by the parent API tab form field values initially.

Attributes

To create a pull-down menu on the frontend product page a custom product attribute is needed. Below is an example of how to set this up with a Variable product that has three variations of the same product with different API Key activation limits.

Under the Variations tab a Default Form Value will need to be set as shown below.

The frontend product page will then display the different activation limit and pricing for each variation of the variable product as shown below.

API Key Types ↑ Back to top

After an API product, which defined as an API Resource, is purchased, an API Key can be used to access that API Resource after the client software activates the access to the API Resource with the API Key.

Master API Key Product Order API Key Associated API Key
Can be used to access and activate any API Resource. Is used to access and activate a single API Resource from the order. Is used to access and activate a single API Resource from the order.
Can be changed by the store administrator. Cannot be changed. Should not be changed.
Every customer has one unique Master API Key. Is always unique. Must always be unique.
A new unique API Key is created for each product purchased on a new order. A new unique API Key is created for each product purchased on a new order.
Is always created for each API Resource on an order. Is only created by a third party plugin or imported, and is required to be assigned to each API product when it is purchased as an API Resource.

User Profile ↑ Back to top

Master API Key ↑ Back to top

The store administrator can control the user Master API Key under Users > “user profile.” Under the API Manager API Key section, the Master API Key can be replaced, and disabled, but never deleted permanently. If the Master API Key is disabled, the Product Order API Keys, and Associated API Keys, available to the user will also stop working. A disabled Master API Key means no access to API Resources for the customer.

Order Screen ↑ Back to top

After a customer purchases an API Product/API resource, the API access information will appear on the Order screen, and in the My Account dashboard. On the Order Screen there will be three meta boxes: Master API Key, API Resources, and API Resource Activations.

If the order has a subscription, those API Resources and API Resource Activations will be displayed on the subscription’s parent order.

Master API Key ↑ Back to top

The Master API Key is displayed on each Order screen for reference.

API Resources ↑ Back to top

The API Resources meta box displays information about the API Resource:

Product Order API Key
Always unique, and used only as an option.
Activation Limit
Can be changed to give the customer more activations.
Resource Title
Makes product identification easier.
Product ID
The unique ID used by the API Manger to identify a specific API Resource when clients send API requests.
Access Expires
All API Resource access is governed by a subscription type time limit, that can optionally be indefinite.

API Resource Activations ↑ Back to top

API Key Used
Displays the API Key type.
Product ID
The product ID number.
Time
Time API Key was activated.
Object
Where/what activated the API Key.
Delete
API Key activation can be deleted.

My Account Dashboard ↑ Back to top

API Keys ↑ Back to top

The API Keys page displays the unique Master API Key that can be used to activate any, and all, API Resources, and the API Resources table. The API Resources table shown below displays the Product Order API Key. Each product is listed individually alongside the corresponding Product Order API Key. If more than one order for the same product was made, each product order item would appear on different rows in the table, and their API Key activations available would be totalled individually.

API Keys table

API Resources in the API Keys table:

Product by Product #

Displays the product title and product ID number.
Product Order API Key
The unique API Key used to access and activate a single API Resource from the order.
Expires
The time limit for the API Resource. This example shows API Resources with indefinite limits.
Activations
The number of activations used out of the total activations available.

The Delete button will remove an activation.

The API Resources table shown below hides the Product Order API Key. Hiding or displaying the Product Order API Key can be set on the API Manager settings screen. In the table below, each of the same product is grouped together, even if they were purchased on different orders, and their API Key activations available are totalled together.

API Downloads ↑ Back to top

API Downloads table

Product by Product #
Displays the product title and product ID number.
Version
The version of this API Resource.
Version Date
Date this download was released. Value set on the product edit screen.
Documentation
A link to the Changelog and Documentation pages, if either value was set on the product edit screen.
Download
A local, an Amazon S3, or remote URL to download the API Resource. The URL is secure, and expires between 5 – 60 minutes after the page is loaded, depending on the settings value. If a Dropbox key value was set in settings, the customer can save the API Resource directly to their Dropbox account.

Pre 2.0 API Keys ↑ Back to top

What happened to the API Keys that existed before version 2.0? The old API Keys were migrated to the Associated API Key database table. The Associated API Key database table can be used to associate a custom API Key to a product, and assigned to that product when it is purchased. The old API Keys, pre 2.0, are considered custom API Keys since they vary from the current API Key format. The Associated API Keys are not displayed in the My Account dashboard, or on the backend Order screen, at this time. We are looking at a meaningful way to display the Associated API Keys that will work best for all use cases.

Database Caching ↑ Back to top

Expensive database queries can be cached to dramatically increase the speed of critical services such as the API responses, and minimize server load. If object caching is configured on the server, the speed boost will be even more dramatic. Cached database queries are also cleaned up automatically on demand to keep the server running optimally.

API Documentation ↑ Back to top

Postman is recommended for remote API testing.

The original intent of the API Manager was to provide API Key management, and software updates, for WordPress plugins and themes, however, over time this evolved to allow use cases for software, services, and everything in-between. The response data from the APIs can be appended and modified using filters to expand the use case possibilities. This documentation summarizes the default use.

Some required query string keys such as plugin_name and slug are used for WordPress plugin and theme software updates. If the software is not a WordPress plugin and theme, then any values can be paired withplugin_name and slug, since the desired response from the API in this case is a download URL (package), and new version available as part of the data needed to determine if a software update is available.

Some API responses may duplicate some data for backward compatibility pre version 2.0, which allows legacy client software to continue to work with version >= 2.0.

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 PHP Library from the private Github repository 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.

Description of keys sent in HTTP(s) API requests: ↑ Back to top

  • request – 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.

What is an instance ID? ↑ Back to top

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 PHP client library provided in our private Github repository that is used to connect WordPress plugins and themes to the API Manager, we use a core WordPress password generator.

Trusted Sources ↑ Back to top

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. 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.

HTTP(S) request ↑ Back to top

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:

http://dev.toddlahman.com/?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:

http://dev.toddlahman.com/?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 request={value}. Below is a list of values for the request key.

  • request=activate
  • request=deactivate
  • request=status
  • request=information
  • request=update
  • request=plugininformation (Deprecated: for legacy use only)
  • request=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:

http://dev.toddlahman.com/?wc-api=wc-am-api&request=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 function requires, along with other details.

request=activate ↑ Back to top

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:

http://dev.toddlahman.com/?wc-api=wc-am-api&request=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": {
        "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"
}

request=deactivate ↑ Back to top

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

Response format: JSON

Required keys: api_key, product_id, instance.

Example query string:

http://dev.toddlahman.com/?wc-api=wc-am-api&request=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": {
        "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"
}

request=status ↑ Back to top

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.)

Example query string:

http://dev.toddlahman.com/?wc-api=wc-am-api&request=status&instance=p1uOusaNM5ub3&product_id=62912&api_key=448567cf667c299bb706df6fe64ed2b44c7d37ba

Example JSON success response:

{
    "status_check": "active",
    "success": true,
    "data": {
        "total_activations_purchased": 4,
        "total_activations": 4,
        "activations_remaining": 0,
        "activated": true
    },
    "api_call_execution_time": "0.021769 seconds"
}
{
    "status_check": "inactive",
    "success": true,
    "data": {
        "total_activations_purchased": 4,
        "total_activations": 3,
        "activations_remaining": 1,
        "activated": false
    },
    "api_call_execution_time": "0.01851 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"
}

request=information ↑ Back to top

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:

http://dev.toddlahman.com/?wc-api=wc-am-api&request=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": "http://dev.toddlahman.com/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:

http://dev.toddlahman.com/?wc-api=wc-am-api&request=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": "http://dev.toddlahman.com/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"
}

request=update ↑ Back to top

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:

http://dev.toddlahman.com/?wc-api=wc-am-api&request=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": "http://dev.toddlahman.com/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:

http://dev.toddlahman.com/?wc-api=wc-am-api&request=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": "http://dev.toddlahman.com/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"
}

request=plugininformation ↑ Back to top

Response format: serialized

Same as request=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.

request=pluginupdatecheck ↑ Back to top

Response format: serialized

Same as request=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.

Troubleshooting ↑ Back to top

As mentioned in the Settings section, several different options are available to log API requests and responses by turning those options on in the API Manager settings page. Postman is recommended for API testing.

API Load/Speed Test ↑ Back to top

Test Description ↑ Back to top

The ab – Apache HTTP server benchmarking tool was used to test the WooCommerce API Manager API Status function in three test cases. All tests were performed using an HTTPS connection which is much slower than an HTTP connection.

  1. 500 API requests with 10 request concurrency.
  2. 500 API request with 1 request concurrency.
  3. 500 API request with 100 request concurrency.

Server Configuration ↑ Back to top

  • Intel(R) Xeon(R) CPU E5-2630 0 @ 2.30GHz, 2 cores
  • CentOS Linux 7.6.1810
  • 2 GB Ram
  • Web server is Nginx 1.14.2 setup for HTTP/2
  • PHP processor is PHP-FPM
  • PHP version 7.2.16
  • MySQL version 5.7.25-log
  • WooCommerce version 3.5.6
  • WordPress version 5.1.1
  • WooCommerce API Manager version 2.0.11
  • No caching was used. (Imagine if caching was used)
  • SSD hard drive, that comes standard on DigitalOcean servers. This server is $15/month.

The server used in the test is the live server at toddlahman.com, which has a large database of customers, so the test could reflect a real-world result.

Test Results ↑ Back to top

Response times for requests are measured in milliseconds. A millisecond is a thousandth of a second, or 0.001 seconds, so 0.001 seconds is 1 ms (millisecond).

Test 1 result:

  • 500 requests with 10 requests concurrency.
  • Time to complete test was 20 seconds.
  • Mean time per request of 40.77 ms (milliseconds), which is 0.04 seconds.
  • Mean requests per second 24.53, which is 1,471.8 per  minute, or 88,308 per hour.
  • Zero failed requests.

The time factor depends greatly on the slowness of HTTPS encryption.

Test 2 result:

  • 500 requests with 1 request concurrency.
  • Time to complete test was 41 seconds.
  • Mean time per request of 82 ms (milliseconds), which is 0.082 seconds.
  • Mean requests per second 12.19, which is 731.4 per  minute, or 43,884 per hour.
  • Three failed requests.

The time factor depends greatly on the slowness of HTTPS encryption.

Test 3 result:

  • 500 requests with 100 requests concurrency.
  • Time to complete test was 21 seconds.
  • Mean time per request of 42 ms (milliseconds), which is 0.042 seconds.
  • Mean requests per second 23.58, which is 1,414.8 per  minute, or 84,888 per hour.
  • Zero failed requests.

The time factor depends greatly on the slowness of HTTPS encryption.

The WooCommerce API Manager performed extremely fast, and reliably under heavy loads without caching enabled. In fact, the WooCommerce API Manager performed better as the request load increased, and at a rate of between 43,884 to 88,308 requests per hour, or 12.19 to 24.53 requests per second. It is safe to say the WooCommerce API Manager can scale to meet the needs of the smallest to the largest WooCommerce store, but would perform even better with caching enabled.

Overriding templates ↑ Back to top

Templates in the WooCommerce API Manager can be overridden using the same approach as is used to override a WooCommerce template. Directions are as follows: http://docs.woocommerce.com/document/template-structure/.

WooCommerce API Manager Hook Reference ↑ Back to top

WooCommerce API Manager Hook Reference

Data Structures and Storage ↑ Back to top

Data Structures and Storage

Troubleshooting ↑ Back to top

No file defined or Software Download/Update Failed ↑ Back to top

When a Downloadable file is added to a product, that first file URL is used for software updates and My Account API Downloads. Prior to API Manager 2.0 the woocommerce_downloadable_product_permissions table was used to verify download permission, and other criteria, but it has created unexpected issues over time, as a result the API Manager no longer relies on the woocommerce_downloadable_product_permissions table for local server download data as of version 2.0.7, but rather only looks for the first Downloadable files URL on the product. One of the issues in using the woocommerce_downloadable_product_permissions table began in WooCommerce version 3.0. Please read https://docs.woocommerce.com/document/digital-downloadable-product-handling/ for more information on how adding/changing Downloadable files URLs on products after WooCommerce 3.0 would cause download/update URLs to stop working.

If the error message “No file defined” appears for a local server download, check that the product has a Downloadable files URL, and it is the first file listed. If the error persists, try removing the Downloadable files, update the product, and add them back, then click update again. Misconfigured web servers, firewalls, or file blocking rules in a plugin or the web server can also cause file download failures. To completely avoid the local server download issues serve downloads from Amazon S3.

Prior to API Manager 2.0 an alphanumeric Software Title was used to find the correct product so the download file URL could be used for software updates and My Account > API Downloads. The documents at that time expected variable product variations to be setup with the exact same product using the exact same download file URL, having the exact same Software Title, and only differing by the number activations, however some stores used the same Software Titles for all the products on the store, and the same file, while others had created a multitude of other variations of this concept, which caused many issues. API Manager 2.0 now uses a numeric Product ID that matches the product’s ID exactly rather than the Software Title, and although the API Manager tries to accept the old Software Title when sent by client software, the issues can sometimes become even more pronounced since the API Manager 2.0 has become more strict in how it uses the Software Title to find the Product ID to then find the correct download file URL. When this translation of the old Software Title breaks, the software updates also break. To fix this issue it is required that all client software send the numeric Product ID and not the alphanumeric Software Title. If hard coding the Product ID into client software is too cumbersome, add a form field to allow the customer to add the Product ID themselves. The Product ID can be found by customers under the My Account > API Keys > Product ID column, and it is sent with all completed order emails.

Preventing Unauthorized Software Use ↑ Back to top

The API Manager can be used to prevent software, or a service, from being used until after the API Key has been activated. Our private Github repository has a PHP Library that can be used for WordPress Plugins and Themes, which demonstrates an example to prevent use of software until after the API Key has been activated. This method can also be used to disable software if the API Key has expired. How this is implemented is completely up to the software author. A close examination of the API functions will provide more information on which will be needed to take appropriate action.

The approach taken most often is to allow the customer to continue using the software after the API Key has expired, just like a desktop version of the software would, but to deny software updates, which the API Manager will do if the API Key time limit for that API Resource has expired. If the software is still in use the customer can still see if software updates are available even after the API Key time limit has expired, but the customer cannot get the update until they renew the API Key time limit through a new purchase, or renewing a WooCommerce Subscription.

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top