WooCommerce API Manager

WooCommerce API Manager Recommendations

↑ Back to top

Existing Store Setup

↑ Back to top

Setting up a WooCommerce store with existing products and orders with the WooCommerce API Manager is accomplished as follows:

1. Edit each product to be used with the WooCommerce API Manager by selecting the API checkbox, then filling in the API tab form, and if it is a variable product variation, a few API Manager details such as the number of activations.
2. API Resources will be automatically created from Order line items that contain those products selected as API products. Order line items that contain WooCommerce Subscription product types will also be automatically created. All API Resources are now accessible with client software or an online service through the APIs.
3. Either add the WooCommerce API Manager PHP Library for Plugins and Themes to your plugin or theme, or build an API client to connect to the API Manager APIs according the the documentation to take advantage of all the features available.
4. Done.

Migrating from Other License Managers

↑ Back to top

• WooCommerce Software Add-on
  • The WooCommerce API Manager has a built-in tool to import WooCommerce Software Add-on data into the API Manager. The API Manager can also answer API queries intended for the WC Software Add-on, so it is safe to delete the WC Software Add-on once the data import has been completed. Clients can migrate at their own pace to new client software that takes advantage of the API Manager’s robust API features.

L-1 Support Policy

↑ Back to top

WooCommerce has an L-1 support policy, which the WooCommerce API Manager also supports to keep any dependencies aligned with WooCommerce, WordPress, and WooCommerce Subscriptions when that extension is installed. This means we will support the latest version and the previous version of the WooCommerce API Manager. This also means you are required to have installed the latest version or the previous version of WooCommerce, WordPress, and WooCommerce Subscriptions when that extension is installed.

Questions & Support

↑ Back to top

WooCommerce.com has their own chat and support/communication form used to contact them directly. We are a third party developer, so you will need to use this support form for any and all communication with us. If you tried to contact us through WooCommerce.com we will redirect you back to the support form.

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.

How to Ask for Support

↑ Back to top

1. Fill out this support form via the Help Desk. Without all the details the support form provides about your installation, support is hampered. Support will not be provided if the support form in not used.
2. Provide a clear explanation of the issue, including how support can reproduce the issue, provide screenshots, or provide login credentials for support to see for themselves and take a closer look.
3. Do not talk about how nothing is working, how much it is costing you, or blame the software. Frustration is always an issue when something isn’t working as expected, but it is contagious, and is counterproductive. Stay focused, and follow number 1 and 2. Problems get solved quicker when everyone works together. We are happy to help.

PHP Library

↑ Back to top

Using the PHP Library

↑ Back to top

The WooCommerce API Manager PHP Library for Plugins and Themes  with the code needed to connect a plugin or theme to the PHP Library after it has been dropped into the plugin or theme. The second argument in the code block example below is for the product_id. If the product_id is left blank the customer enters the product_id, if the product_id is hard coded, then the customer will not need to enter the product_id.

Once the product is activated, a notice is displayed for the customer to activate the plugin or theme.

On the activation screen, if the product_id was hard coded then the customer only needs to enter the API Key. If this is a variable product variation, each version of the software will require a separate file with the correctly hard coded product_id matching the customer’s product purchase. This is why not hard coding the product_id is the preferred method for variable product variations as shown in the next example.

On the activation screen, if the product_id was not hard coded then the customer needs to enter both the API Key and the product_id. This is the preferred method for variable product variations.

After the plugin is activated, the number of activations remaining is displayed.

Orders that have API Key activations will display a key in the orders list.

On the order screen, the activations will be listed.

When an update is available the update details will be displayed. Plugins and themes can be updated automatically just like any other plugins and themes.

Click on the view version details link will display the details you have provided and configured just like any other plugins and themes.

After the plugin is deactivated, the activations remaining is displayed.

Using Postman for Testing

↑ Back to top

A preconfigured Postman .json file collection template is included to make it easy to test the API functions. Server URL, and keys/values, will need to be modified specific to your product and server.

Software Update File Hosting

↑ Back to top

The file used for software updates can be hosted on the local server, Amazon S3, or from any remote URL. The file download URL is wrapped in a secure URL that expires after the expire time you set.

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.

Always test your current PHP Library in your client software to make sure it works with the new version of the API Manager, especially if a major version is released.

Upgrading From Version 1.5.4 to 2.x

↑ Back to top

The client software for plugins and themes was called the PHP Library and is now referred to as the WooCommerce API Manager PHP Library for Plugins and Themes. As of API Manager version 2.0 the Product ID is required to be sent with each  API call/API request depending on the API function and request type. See the API documentation. As of API Manager version 2.1, there was a change to the API to fix an issue created by some firewalls that block commonly used API call/API request query keys. Variable Products and Variable Subscriptions must send the Product ID (an integer) or software updates will break. Simple Products and Simple Subscriptions can still send the old Software Title, however the Product ID (an integer) is faster, and ensures future compatibility. For these reasons all client software must be updated for  WooCommerce API Manager version 2.x. Customers who purchased Variable Products and Variable Subscriptions will need to update software manually, while Simple Products and Simple Subscriptions customers can use the one-click update.

API Server Hosting

↑ Back to top

Web hosts control all traffic going in and out of a WooCommerce store. This can be problematic when the web host unknowingly blocks traffic, or has caching that is too aggressive, both of which can cause the API Manager APIs (Application Programming Interfaces) to break. It is not easy to track down and fix these issues, so it is highly recommended to host your own server, or virtual server through Amazon, Google, Microsoft, or Digital Ocean. Todd Lahman LLC uses and prefers Digital Ocean due to their low cost, ease of use, advanced features, reliability, worldwide network, and MySQL database hosting.

Extensions

↑ Back to top

API Manager Product Tabs

↑ Back to top

WooCommerce API Manager Product Tabs plugin adds WooCommerce API Manager Product document tabs to the frontend product page when using a theme that supports tabs such as the Storefront theme. WooCommerce Products will be automatically populated with tabs, and content for those tabs, when the product is an API Manager Product. Just setup the API Products as usual, and WooCommerce API Manager Product Tabs does the rest, so you don’t need to write the same content a second time into tab metaboxes on the product. Here is a brief description of how it works.

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

↑ Back to top

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');

Amazon S3 Region

↑ Back to top

An Amazon S3 region must be chosen, and is listed in the Amazon S3 dashboard in the bucket details row. Pick one, and put all your files in that bucket. A bucket can be organized into folders if needed.

Download Links

↑ Back to top

URL Expire Time: Download URLs on the My Account dashboard, and for software updates, can be set to expire between 1 to 7 days after they are generated. Each download URL is generated on request, and expires to prevent download abuse on sites other than yours. Since download URLs have an expiration date they are not sent in emails after a 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 Keys

↑ Back to top

Product Order API Keys: The Product Order API Keys can be hidden if you want clients to only use the single Master API Key to activate API resources.

Master API Key: Although it is inot recommended, the Master API Key can be hidden from the client.

Grace Period

↑ Back to top

Grace Period: This is the time interval before renewable API Resource(s) and API Key activations will be deleted after the API Resource subscription has expired. This allows the client an opportunity to renew the subscription before the API Resource(s) and API Key activations are deleted. The interval can be set to any time interval, or zero for no grace period.

API Doc Tabs

↑ Back to top

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 Resources Cleanup

↑ Back to top

Schedule API Resources Cleanup: Every week a cleanup process will deleted expired or cancelled subscription API Resources and the associated API Key activations. This process can be turned off, but it is recommended to keep it on. API Resources are still checked and deleted on-demand when a client interacts with the store or the administrator interacts with the store.

API Resources and API Key activations are ephemeral, and are only meant to last during the subscription interval. All the data to rebuild an API Resource still exists in the WooCommerce database tables.

API Response

↑ Back to top

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

Debug

↑ Back to top

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

The API Error Log has been enhanced to determine which clients are erroneously querying the API endpoints.

Postman is recommended for remote API testing.

Migrations

↑ Back to top

WooCommerce Software Add-on: Selecting this option in settings allows the API Manager to listen for and reply to API queries intended for the WooCommerce Software Add-on from those clients.

The API Manager can import the data from WooCommerce Software Add-on using the WooCommerce > Status > Tools > Import WC Software Add-On Data button.

Disable Caching

↑ Back to top

The API Manager has a SmartCache engine that dynamically caches data to reduce server resources, and keep data flowing without delay. There is no option on settings to disable the SmartCache engine.

The SmartCache engine can be disable using the code

define( 'WC_AM_ENABLE_CACHE', false );

in wp-config.php. This can be useful for developers when testing requires realtime results.

Amazon S3 Setup

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

SmartCache Engine

↑ Back to top

The API Manager uses SmartCache Engine to cache database and API queries at critical points in the data process to dramatically increase the speed of critical services such as data and API responses. SmartCache only updates the cached data being requested when the data changes, or when expired cache is requested but needs to be refreshed. The result is a dramatic speed increase, and a dramatic decrease in server load. When SmartCache is combined with object caching the result is blazing fast speed. SmartCache allows the API Manager to effortlessly scale to any level of traffic load.

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.

Flexible Product Types

↑ Back to top

The WooCommerce API Manager allows product creation based on your sales model, and the structure provided by WooCommerce. An API Resource (Product) can be sold as a simple/simple subscription product, or a variable/variable subscription product with variations. Each simple and variable variation can have a single number of activations, or unlimited activations, for purchase, or for variable product variations, each variation can have a different number of activations, including one variation that has unlimited activations.

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.

Unlimited Activations: Sets a default number of activations to 100,000. If Unlimited Activations is selected, then Activation Limit is hidden. This number can be increased using the filter hook wc_api_manager_unlimited_activation_limit. All resources are limited. Increasing this to a larger number than your Operating System can handle can cause expected resource limitation issues, so either keep the default, or choose something reasonable. Once this option is enabled, customers who already  purchased this product will have their API Key activation limit increased to match the limit value that is set, but the update is only triggered when the customer data for the product is pulled from the database, such as when the customer views the My Account dashboard > API Key tab. This minimizes the resources needed to implement this feature for a product that exists on a lot of orders.

Activation Limit: Sets the API Key activation limit for the product. If the number is set above 100,000, the set the product for Unlimited Activations. If Unlimited Activations is selected, then Activation Limit is hidden.

The remaining fields are docs linked to plugin “view details” tabs. All docs are optional except for the Changelog. Once a page/doc is selected, an Edit link appears. The docs that are displayed can be enabled/disabled on the settings screen.

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.

Free Products

↑ Back to top

It is possible to create free products, just set the price to zero. It is also possible to give an existing customer a product for free by creating an order assigned to the customer, and adding the product for zero cost. To access the free product, free API Resource, customers will still be required to create, or have, an account as a login is required to maintain API endpoint security.

API Key Types

↑ Back to top

After an API product, which is 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. Product Order API Key and Associated API Key are granted limited privileges by the Master API Key.

Master API Key	Product Order API Key	Associated API Key
Great for customers who want to use a single API Key for everything.	Great for store owners who want customers to use separate API Keys for each purchase.	Just like the Product Order API Key, except you are in control of which products and orders it is associated with.
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.

The Master API Key can be used for any and all API Resources. As API Resources are added or removed, the Master API Key keeps track of those resources, and only allows access to the API Resources available. For example, if a customer buys the same API Resource twice, it accumulates the activations, and if that API Resource is a subscription, then it will reduce the activations when one of the subscriptions is no longer in Active or Pending Cancellation status or add more activations when a new subscription for that API Resource is added.

The Product Order API Key and Associated API Key get their privileges from the Master API Key, and only manage a single API Resource from a single order. If a new order for the API Resource is generated, a new Product Order API Key is generated to manage that API Resource, which means the customer will need to deactivate their software and reactivate using the new Product Order API Key. This is especially true if the API Resource is a subscription. It is always best practice for subscription customers to use the Master API Key.

API Key/License Key Model

↑ Back to top

There are several types of API Key, or Licensing, models that exist, for example node-locked, OEM, and floating.

• A node-locked license is an API key for use on one computer, and is tied only to that computer.
• An OEM license unlocks software preinstalled, for example, windows using an API Key.
• A floating license is an API Key that can be used to unlock a computer or software if there is a free license available.

The API Manager uses a floating and OEM license model for API Keys. The API Manager assigns a limited number of API Key activations per product purchase. When an activation is used, there is one less activation available for other software or computers to use as in a floating license model, and if an activation is deactivated, then that activation can be used by other software or computers. This model can also be used for OEM.

The Product Order API Key can limit those activations for a specific product on a specific order.

The Associated API Key can use imported, or local server generated API Keys, assigned to a product, and then assigned when an order is placed for that product. The Associated API Key could be as an example, Windows OEM license keys customers can use to activate their product.

The API Manager expects the API Key used to request activation, along with other values as defined by the API function, documented below.

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.

If the Master API Key is replaced, all activations for the user who owns the Master API Key will be deleted. Activations created using the Product Order API Key, and Associated API Key, are also deleted when the Master API Key is replaced. Product Order API Key and Associated API Key are granted limited privileges by the Master API Key.

Disable User Account

↑ Back to top

When the API Manager API Key > Disable Master API Key box is checked on the User Profile, the user will no longer have access to any API functions even if valid activations exist. The user account will be completely disabled, and the My Account dashboard will reflect this disabled status.

User Switching Plugin

↑ Back to top

The User Switching plugin is a very useful tool that allows the store owner/manager to virtually login as a user. Once switched to the user login the user’s My Account dashboard can be viewed, along with the API Keys and API Downloads tab. This is useful when troubleshooting, investigating issues, and confirming template overrides are working as expected from the user’s view. Don’t forget to switch back using the switch link. Do a Google search for tutorials on how to get the most out of the User Switching plugin.

Order Status

↑ Back to top

By default API Resources only exist for orders that have a “completed” status. API Resources for the order status “processing” will only exist if WooCommerce > Settings > Products > Access Restriction > “Grant access to downloadable products after payment” is selected. Orders that have a “processing” status before “Grant access to downloadable products after payment” is selected will not have API Resources available until the order status has changed to “completed,” or the order is new and has a “processing” status, or has been changed to “processing” status.

Orders not in completed status, or processing status if other conditions are met, will have the API Key activations, and API Resources, deleted. If the order is placed back into completed status, or processing status if other conditions are met, the API Resources will be recreated, but the API Key activations will not. Why are activations deleted? Client software will, or should, receive an error if it tries to send a query with a Product ID that is no longer considered active, but the customer may not realize he/she would need to delete activations in his/her My Account dashboard before reactivating the client software, so those activations are deleted to eliminate known support issues customers commonly have related to this. All the customer should have to do once they have brought their account back into good standing is to reactivate their software.

See the WooCommerce Subscriptions section regarding Subscription statuses.

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.

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.

WooCommerce Subscriptions

↑ Back to top

Order Screen

↑ Back to top

Orders containing WooCommerce Subscription line items are displayed based on how WC Subscriptions works. All WooCommerce Subscriptions have the API Resources and API Resource Activations displayed on the WooCommerce Subscriptions Parent order screen.

API Resources and API Resource Activations will be displayed on the Switched Subscription order screen rather than the parent order screen after the client chooses to switch their subscription.

Subscription Status

↑ Back to top

A subscription is only considered active if it has a Active or Pending Cancellation status. As mentioned in the Order Status section, any order not in completed, or processing if other conditions are met, status will be considered inactive. WooCommerce Subscriptions has its own subscription statuses, but it shares one with WooCommerce, and that is the on-hold status, which is considered an inactive subscription. Read the following sections to see how API Keys are handled in these situations.

Switched Subscription

↑ Back to top

A WooCommerce Subscription product that is a Variable Subscription type has a Parent product that has one or more variation products, each with their own unique Product ID created by WooCommerce, and used by the API Manager to identify each variation, and locate information stored for that product, such as the download URL for software updates. Client software, such as the API Manager PHP Library, must authenticate using a Master API Key, or a Product Order API Key, and the Product ID unique to every product in the WooCommerce store.  If a Subscription has been switched to a different Variable Subscription product variation, the API Resources and API Resource Activations will be displayed on the Switched Subscription order screen rather than the parent order screen, and the Product Order API Key will change, but the Master API Key will remain unchanged. The API Resource Activations for the switched Variable Subscription product variation will be deleted because the Product ID will have changed. If the API Resource Activations were not deleted, the client would receive an error the next time the client software checked for a software update, and the client would see many activations already exist for a product they are no longer subscribed to, and the client would need to login to the My Account dashboard, go to API Keys, and figure out which activations to delete for a product they no longer subscribe to.

If the client is using a Product Order API Key then the client needs to change the Product ID and the Product Order API Key, or download new software that has the Product ID, to reactivate the API Key. If the client is using a Master API Key then the client only needs to change the Product ID, or download new software that has the Product ID, to reactivate the API Key. It is much easier for the client to always use the Master API Key with WooCommerce Subscription products.

The API Manager currently has an API Access Expires field for Simple Product types that are not a WooCommerce Subscription product. In the future it is planned to allow this to become a feature rich alternative to WooCommerce Subscription products, that will allow clients to increase/decrease activations without changing subscriptions, and to continue to use the same activations without disruption.

API Key Expiration

↑ Back to top

API Keys for WooCommerce Subscription products will only work if the subscription has an Active or Pending Cancellation status. If a subscription has a status other than Active or Pending Cancellation status, and the client queries the API, views the API Keys or API Downloads, or if the store owner views an order containing an API Product, the API Manager automatically checks if the API Products still have an Active or Pending Cancellation status, and if not then the API Key activations associated with that API Product are deleted.

Subscriptions not in Active or Pending Cancellation status, and orders not in completed status, or processing status if other conditions are met, will have the API Key activations, and API Resources, deleted. If the order is placed back into completed status, or processing status if other conditions are met, the API Resources will be recreated, but the API Key activations will not, which also applies to a subscription that returns to Active status. Why are activations deleted? Client software will, or should, receive an error if it tries to send a query with a Product ID that is no longer considered active, but the customer may not realize he/she would need to delete activations in his/her My Account dashboard before reactivating the client software, so those activations are deleted to eliminate known support issues customers commonly have related to this. All the customer should have to do once they have brought their account back into good standing is to reactivate their software.

API Manager Dashboard

↑ Back to top

API Customers

↑ Back to top

The API Customers dashboard.

The API Customers dashboard lists sequential API Resources ordered by User ID by default. Each API Resource represents an order line item that is an API Product. Some column are sortable. The search box can be used to find API Resources by User ID, Order ID, Product ID, or by an email address that is also used on the User profile. The email address has been obfuscated in the screenshot above.

There are links to additional resources that open in a new tab. For example, to manage the number of activations or extend its expiration time, the Order ID link will open the order for the API Resource, and the API Key activations can also be viewed or managed on the same order screen.

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 with the Product Order API Keys Not hidden

API Resources in the API Keys table:

Product Title

Displays the product title and product ID number.

Product ID

Displays the product ID number that is required in most API requests.

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.

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

API Keys table with the Product Order API Keys hidden

API Downloads

↑ Back to top

API Downloads table

Product Title

Displays the product title and product ID number.

Version

The version of this API Resource.

Release 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 wrapped to make it a secure URL, and it expires between 1 – 7 days 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.

API Documentation

↑ Back to top

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.

Description of keys sent in HTTP(s) API requests:

↑ Back to top

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

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 WooCommerce API Manager PHP Library for Plugins and Themes 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.

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.

HTTP(S) Requests

↑ 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:

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=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 function requires, along with other details.

wc_am_action=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:

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"
}

wc_am_action=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:

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"
}

wc_am_action=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 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"
}

wc_am_action=product_list

↑ Back to top

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.

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"
}

wc_am_action=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:

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"
}

wc_am_action=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:

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"
}

wc_am_action=plugininformation

↑ Back to top

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.

wc_am_action=pluginupdatecheck

↑ Back to top

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.

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-2650 v4 @ 2.20GHz, 2 cores
• CentOS Linux 7.6.1810
• 2 GB Ram
• Web server is Nginx 1.16.1 setup for HTTP/2
• PHP processor is PHP-FPM
• PHP version 7.3.9
• MySQL version 5.7.27-log
• WooCommerce version 3.7.0
• WordPress version 5.2.3
• WooCommerce API Manager version 2.2.3
• No caching was used. (Imagine if caching was used)
• SSD hard drive that comes standard on DigitalOcean servers. It costs $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 19.601 seconds.
• Mean time per request of 39.023 ms (milliseconds), which is 0.039023 seconds.
• Mean requests per second 25.51, which is 1,530.6 per  minute, or 91,836 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 38.382 seconds.
• Mean time per request of 76.765 ms (milliseconds), which is 0.076765 seconds.
• Mean requests per second 13.03, which is 781.8 per  minute, or 46,908 per hour.
• Zero 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 19.105 seconds.
• Mean time per request of 38.211 ms (milliseconds), which is 0.038211 seconds.
• Mean requests per second 26.17, which is 1,570.2 per  minute, or 94,212 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: https://woocommerce.com/document/template-structure/.

WooCommerce API Manager Hook Reference (Not Completed)

↑ Back to top

WooCommerce API Manager Hook Reference

Data Structures and Storage (Not Completed)

↑ Back to top

Data Structures and Storage

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. The documentation for the WooCommerce API Manager PHP Library for Plugins and Themes has an example on how 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.

Troubleshooting

↑ Back to top

Read the Self-Service Guide

↑ Back to top

Review the WooCommerce Self-Service Guide.

Data Update Not Completing

↑ Back to top

The first step is to make sure all plugins, themes, and theme template overrides are up-to-date. If you have your own server, make sure all software is up-to-date. Anything that is out-of-date, and needs to be updated, can throw an error that can prevent things from working in the background even though you are not seeing the error, and out-of-date software is security risk. Also, make sure you know what the latest WordPress, WooCommerce, and WooCommerce API Manager requirements are for versions of PHP and MySQL, as outdated versions can and will cause issues. Keeping software up-to-date is the surest way to avoid a ton of time trying to figure out what is going wrong.

The next step is to disable all plugins except WooCommerce, WooCommerce API Manager, and WooCommerce Subscriptions, if you have that plugin, then see if the data update completes. It could be that the server does not have sufficient RAM to process the update.

Go to WooCommerce > Status and look for recommendations for updates.

Below are some server settings to check, if you have your own server, which are listed below as Apache errors, but are not Apache specific.

1. max_execution_time = 30 – is changed in the php.ini file on Linux servers.
2. max_allowed_packet = 128M – is a MySQL setting and is changed on Linux servers in /etc/my.cnf.

If a data update does not seem to be completing, it could be because the server does not have enough RAM or CPUs to handle the normal workload, and an update as well. The updater in the API Manager monitors the memory usage to make sure it never exceeds 90%, and it will pause if it does then starts again where it left off. Slow servers will take a while to update, and that is compounded by a large database.

If you see 500 Internal Server Error, or Error Connection Timed Out, then the machine either exhausted its memory at that moment, or a plugin or theme is throwing a fatal error. Updating software will prevent fatal errors, and increasing RAM, or modifying WordPress settings to increase memory, will fix memory issues, but only  if there is enough RAM to start with.

Go to WooCommerce > Status > Logs > and check for any fatal-errors … logs.

Go to WooCommerce > Status > Logs > wc_am_db_updates … will display the current status of the API Manager data update process.

If all else fails check the PHP, and web server (Apache, Nginx, etc.), error logs for clues as to what errors are preventing the update process from completing.

Pre 2.0 API Keys don’t work

↑ Back to top

API Keys that existed before version 2.0 still exist, but they have moved to the Associated API Key database table. The pre 2.0 API Keys will still work for activation, deactivation, and status queries, but may not work for updates in all cases if the pre 2.0 version of the PHP Library is being used for WordPress plugins and themes. If updates are not working for pre 2.0 API Keys for WordPress plugins and themes, update to the post 2.0 version of the PHP Library.

Pre 2.0 API Keys will not be displayed on the order screen, or on the My Account dashboard. The Master API Key will be displayed. If set under settings, the Product Order API Key will also be displayed, however the default is to only show the Master API Key.

If you are NOT using the PHP Library for WordPress plugins and themes, then refer to the API documentation to make sure your queries contain all the required keys and values.

“No API resources exist” Error Message

↑ Back to top

If you see the message “No API resources exist” when attempting to activate an API Key, this means no API Resource record could be found for this purchase. To know if an API Resource exists, go to the Order screen where there should be a record in the API Resources meta box. API Resources only exist for an order if the order has a “completed” or “processing” status. The record is searched for using the API Key and Product ID, so check to make sure both of those values are correct on the Order screen API Resources meta box, or the API Keys tab  in the customer’s My Account dashboard.

Make sure to check the product itself, because the API checkbox should be checked on the Product edit screen, or an API Resource will not be created when the product is purchased. Checking the API check box on the Product edit screen after purchases have been made will trigger a background process to create API Resources from completed or processing orders previously made for that product.

If the product is an API product and a WooCommerce Subscription, the API Resource will not be displayed in the Order screen API Resources meta box, be available to the customer via the API, or be displayed in the My Account dashboard, if the subscription has expired.

If the product is an API product, and the API Access Expires time limit has expired, the API Resource will not be displayed in the Order screen API Resources meta box, be available to the customer via the API, or be displayed in the My Account dashboard.

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.

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

Apache error AH01067

↑ Back to top

Error log message: AH01067: Failed to read FastCGI header, referrer: …

Edit the php.ini file to at least max_execution_time 30 or greater, but not too much or PHP scripts will take too long to complete:

max_execution_time = 30 

If you are running a Apache proxy, the timeout must be greater than ( > ) the php max_execution_time.

https://forum.remirepo.net/viewtopic.php?id=3563

Apache error AH01075

↑ Back to top

Error log message: The timeout specified has expired: AH01075: Error dispatching request to …

In the Apache config file set the ProxyTimeout to 1800, or whatever works for you, but the timeout must be greater than ( > ) the php max_execution_time in the php.ini file.

ProxyTimeout 1800

https://support.plesk.com/hc/en-us/articles/115000064929-Website-is-not-accessible-The-timeout-specified-has-expired-Error-dispatching-request-to

Apache error AH01071

↑ Back to top

Error log message: AH01071: Got error ‘PHP message: PHP Warning: Error while sending QUERY packet …

This error happens when the database cannot handle more connections, because there are too many requests for it to handle. If the server is on a shared host, you need to consider upgrading to an account that has a database that can handle more traffic. If you have your own server then edit the /etc/my.cnf file as follows keeping in mind that you can use a lower allocation than 128 MB.:

max_allowed_packet = 128M

https://dev.mysql.com/doc/refman/8.0/en/packet-too-large.html

Migration from Other License Key Plugins

↑ Back to top

Migration from other License Key plugins/add-ons/extensions is easy, such as migration from WooCommerce Software Add-On. There is no need to import any data. Keep your old License Key plugin activated, and setup the WooCommerce API Manager products as shown in this document. Any products setup as API products will have all existing orders with a Completed status automatically setup with API Keys. The only task remaining is to update your client software or service to connect to the WooCommerce API Manager APIs.