WooCommerce API Manager Recommendations
↑ Back to top- It is good practice to update the PHP version before the end-of-life where that version is no longer supported even with security fixes. See current supported PHP versions.
- When upgrading from API Manager pre 2.0 to 2.0 or greater, the data is migrated to custom database tables and the old data is deleted. There is no ability to rollback, or downgrade, to the older version. Test first, backup, and be prepared before upgrading.
- OpenSSL should be kept up-to-date.
- An HTTPS connection to your store is highly recommended.
- The AUTH_KEY and NONCE_SALT constants that should exist in wp-config.php are used by the API Manager for advanced encryption. If these constants are absent go to https://api.wordpress.org/secret-key/1.1/salt/ and add those keys to wp-config.php.
- In wp-config.php define( WP_DEBUG’, false ); If debug displays errors on a live production site it will break API requests.
- Caching the homepage URL query strings will break the APIs. By default the API Manager signals caching plugins to not cache the homepage/root URL to insure query strings are not cached. Read the Homepage Caching section for guidance.
- Be careful with firewalls, since they can break API requests by blocking query strings.
- CloudFlare may cache query strings, so check the settings.
- DO NOT DELETE PRODUCTS if the API checkbox has been selected. Once a product has been selected to be used as an API product, that product ID will become the product_id (an integer) used by the API Manager to identify that product going forward. Deleting the product will break all client API requests for that product.
- If a product is duplicated, make sure the API information is unique to the newly created product.
- As of version 2.1, the API Manager authenticates with Amazon S3 using AWS Signature Version 4.
Existing Store Setup
↑ Back to topSetting up a WooCommerce store with existing products and orders with the WooCommerce API Manager is accomplished as follows:
- 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.
- 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.
- 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.
- 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 topWooCommerce 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 topWooCommerce.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- 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.
- 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.
- 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.
WooCommerce API Manager PHP Library for Plugins and Themes
↑ Back to topDrop-in library for plugins and themes
Using Postman for Testing
↑ Back to topA preconfigured Postman .json file collection template is included to make it easy to test the API endpoints. Server URL, and keys/values, will need to be modified specific to your product and server.
Software Update File Hosting
↑ Back to topThe 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 topThe 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 topIf 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 topThe 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 endpoint 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 topWeb 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 topAPI Manager Product Tabs
↑ Back to topWooCommerce 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 meta boxes on the product. Here is a brief description of how it works.
Settings
↑ Back to topAmazon S3 Setup Instructions
↑ Back to topSmartCache Engine
↑ Back to topThe 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.
API Query and Database Caching
↑ Back to topThere may be scenarios where API query caching and database caching may not be needed, such as during development and troubleshooting. To disable both API query and database caching add the following to the wp-config.php file:
define( 'WC_AM_ENABLE_CACHE', false );Homepage Caching
↑ Back to topBy default the API Manager signals caching plugins to not cache the homepage/root URL to insure query strings are not cached. This is done to make sure mistakes in caching are not made that would break the APIs. This is also helpful during development and troubleshooting. The API Manager listens for HTTP requests on the homepage/root URL. For store owners that know enough to not break the APIs there are several ways to enable caching on the homepage/root URL.
Add the following to the wp-config.php file to allow the homepage/root URL to be cached:
define( 'WC_AM_DISABLE_HOMEPAGE_CACHE', false );After caching is allowed on the homepage/root URL exclude the following query string, and anything that follows it, in the caching plugin, or CDN service such as CloudFlare:
wc-api=wc-am-apiSee the API docs for more information regarding query strings.
Product Setup
↑ Back to topSimple, Variable, and Subscription Product Setup
API Manager Subscriptions
↑ Back to topSetup and Understanding API Manager Subscriptions
API Key Types
↑ Back to topAfter 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 topThere 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 endpoint, documented below.
User Profile
↑ Back to topMaster 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 topWhen 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 endpoints 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 topThe 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 topBy 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 topWooCommerce Subscriptions
↑ Back to topHow the API Manager Works with WooCommerce Subscriptions
API Manager Dashboard
↑ Back to topAPI Customers
↑ Back to topThe API Customers dashboard.
The API Customers dashboard lists essential details for each customer. Each API Resource represents an order line item that is an API Product. Some columns are sortable. The search box can be used to find API Resources by email address, Order ID, Product ID, or by a User ID. 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 topFeatures of the My Account Dashboard
API Documentation
↑ Back to topAPI Specifications and Documentation
Overriding templates
↑ Back to topTemplates 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/.
Preventing Unauthorized Software Use
↑ Back to topThe 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 endpoints 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.