WooCommerce Docs

Documentation, Reference Materials, and Tutorials for your WooCommerce products

Search

WooCommerce API Manager

Important note ↑ Back to Top

There is an API Manager PHP Library available in a private GitHub repo, maintained by the author, to help plugin and theme authors quickly setup products that can utilize the API Manager APIs.

Contact Woo support, and provide them with your GitHub username and purchase license, so the developer can add you to the API Manager PHP Library GitHub repo.

The API Manager PHP Library setup for a plugin or theme takes 5 minutes or less on average.

The WooCommerce API Manager requires PHP 5.6 or greater. End-of-life versions of PHP will not be supported, even if WordPress and WooCommerce do support those versions, so be sure to stay up-to-date. Please review supported and end-of-life versions of PHP at the official support page.

To avoid breaking products ↑ Back to Top

Once a product type is created in WooCommerce, never ever change it to another product type.

For example a product type of Simple product should not be changed to a Variable product. Changing a product type to another product type WILL BREAK how that product works, especially with WooCommerce Subscriptions, and the WooCommerce API Manager.

Also, don’t duplicate an existing product, since it will also duplicate API Manager settings, such as the Software Title described below, and the postmeta _wp_old_slug value, which is used to rewrite old product URLs to new product URLs. Having two products with the same _wp_old_slug value will cause potential customers to be redirected to the old product, or the product that was duplicated. It is best to create a new product, rather than duplicate an old product to due unexpected issues that can result.

Required API Data ↑ Back to Top

Two critical data points are required with every API call, a Product ID/Software Title, and an Instance ID.

  1. The Product ID, and the Software Title, must be unique and it must match exactly. The Product ID value is set in the API Manager plugin, or theme, example code.  The Software Title is set in the Product > API tab > Software Title form field. The Software Title must be unique, and can only be used once for a simple product, or once for a variable product, but can be shared for all variations of a variable product if they all use the same download file. Client software sends the Product ID to the API Manager, then the API Manager finds the Software Title for that product, and uses that information to find the download file used for software updates, and it uses it to find the Software Title that is part of a data array created for the customer’s order, to allow the API Manager to find that data, and authenticate the customer’s API request to activate software and get software updates.api-manager-product-software-title
  2. The Instance ID is essentially a unique token sent to the API for software activation. Once software activates with an Instance ID, it is used for subsequent API calls such as deactivation, status checks, and software update requests. The API Manager uses the Instance ID to identify a device, domain, or location for the installed software, and to lookup data associated with that Instance ID. If software is removed, but fails to deactivate using the Instance ID, that activation will remain until the customer or Admin remove it from the customer’s account. The API Manager PHP Library automatically sends a deactivation request to the API Manager if a plugin or theme are removed from WordPress, but it does cannot take the same action for a plugin or theme removed via SFTP.

How it works ↑ Back to Top

The WooCommerce API Manager secures your software with API License Key activations/deactivations, and provides automatic updates of plugins and themes. Although the WooCommerce API Manager comes with prebuilt PHP classes designed for WordPress plugins and themes, any software application with an internet connection can communicate with the APIs to perform activations/deactivations and software updates.

The API Manager provides two RESTful APIs, a license key API and an update API.

The license key API provides an endpoint for software to activate and deactivate an API License Key that facilitates the authentication needed to access the update API. When a customer purchases a downloadable product, such as a plugin or a theme, an API License Key will be automatically generated, and emailed to the customer to allow them to activate their software.

The update API provides an endpoint for software updates using the core WordPress update API. Customers will then be able to upgrade their software just as they would from WordPress.org from inside their WordPress dashboard. When client software makes an update query, a secure download URL is returned. The download URL can be used by any software, whether written in PHP or some other language, even if it is a non-WordPress application, to perform a software update.

Extension Support ↑ Back to Top

WooCommerce Subscriptions is fully supported. The Software Add-On is no longer supported as of WooCommerce API Manager version 1.3.4, and will cause API conflicts.

WooCommerce extensions that create bundled, chained, composite, grouped, or any other product combination are all supported.

Preparing customer accounts ↑ Back to Top

API Manager Tools
API Manager Tools

When the WooCommerce API Manager is first installed it builds custom data for all customer orders that contain downloadable products. The customer order data is stored in the usermeta database table, as is the activation data.

If there is a catastrophe, and there are no database backups to fall back on, there is a tool to rebuild the data under WooCommerce > Settings > API Manager > API Manager Data.

The WooCommerce API Manager relies on the WooCommerce woocommerce_downloadable_product_permissions database table, so a tool to rebuild this critical table, in the event of a disaster, is also available under WooCommerce > Settings > API Manager > Download Permissions.

Note: Do not enable guest checkout. Customers must have an account for the WooCommerce API Manager to securely handle interactions with client software.

When testing, do not create orders with the Administrator role, instead create orders using either the Customer or Subscriber roles, otherwise you will get an error response from the License Key API.

Simple product configuration ↑ Back to Top

Simple Product General Tab

On the General tab the virtual, downloadable, and API boxes must be ticked, a price must be set, even if it is zero. If the price is set to 0.00, the product will be listed as free. A download file path is set after using the Choose a file button, and uploading your zip file using the Media Library window.

Simple Products can be sold any way that sells, including individually, as bundles, composites, groups, or whatever is available.

Rather than sell multiple copies of software to a single customer, the API License allows a single copy to be sold with a license that can activate one or more installations of that software. If the customer wants more activations, they must purchase another license with the number of activations they need. If the software is sold as a Simple Subscription, the customer can switch subscriptions to upgrade/downgrade the number of activations, for which they will get a new API License Key emailed to them.

Simple Product API Tab

The API Tab form configures all the API options. The Software Title is critical, as it must be unique, and must not change.

The exact Software Title, spaces included, is sent by the client software to the API, which uses that information to help locate the correct product to serve a response. Although the Software Title is the only required field, all other fields down to the Software Activation Limit should be filled out.

The pages below are not required, but it is recommended to provide a Changelog. The pages used for Description, etc., are standard WordPress pages, so any HTML format used from a page will be displayed correctly, even when using images or embedded video. The page drop down menu is also searchable if there are a lot of pages to sort through.

If the Subscriptions extension is activated there will be a checkbox option available that will only allow updates if the customer’s subscription is active.

Software version numbers work best when using single decimal places for example 1.1.2, rather than 1.12.

Note: Themes do not use the pages, such as Description, etc., in their “view details” page, but do use the Software Page URL to display the “view details” for an update. The form should still be filled out completely for every product.

Variable product configuration ↑ Back to Top

api-manager-variable-product-downloadable

Variable Products are setup in a parent and child relationship. The variation (child) settings are configured under Variations. The API checkbox needs to be ticked before continuing to make the API tab available for Global settings.

Variable Products can be sold any way that sells, including individually, as bundles, composites, groups, or whatever is available. Rather than sell multiple copies of software to a single customer, the API License allows a single copy to be sold with a license that can activate one or more installations of that software.

If the customer wants more activations, they must purchase another license with the number of activations they need. If the software is sold as a Variable Subscription, the customer can switch subscriptions to upgrade/downgrade the number of activations, for which they will get a new API License Key emailed to them.

The API tab for Variable products is used for Global Settings.

Anything set on this form will be used for all variable products, but only if the Global Settings box is ticked. The API tab makes it easy to quickly configure variable products when they will all be using the same information.

The one global setting that cannot be set is the activations limit, which is set individually for each variable product. If the global settings are used, the Software Title is critical, as it must be unique, and must not change. The exact Software Title, spaces included, is sent by the client software to the API, which uses that information to help locate the correct product to serve a response.

If the Subscriptions extension is activated there will be a checkbox option available that will only allow updates if the customer’s subscription is active.

Note: Themes do not use the pages, such as Description, etc., in their “view details” page, but do use the Software Page URL to display the “view details” for an update. The form should still be filled out completely for every product.

Software version numbers work best when using single decimal places for example 1.1.2, rather than 1.12.

Attribute Tab

The Attributes tab allows the Variations (variable products) to be set. Click Save attributes, then click update/save the product settings before continuing.

Attributes Types

Once the attributes are setup they will be displayed as a pull down menu on product page listing the pricing and licensing/activation options.

On the Variations tab, each variable product will have a pull down menu listing the attributes, so each product will need to choose one. The Default selection pull down menu will choose the selection that will be selected as the default when the product page loads on product page.

The Enabled, Downloadable, and Virtual checkboxes will all need to be ticked. The price and file path will also need to be set. If the price is set to 0.00, the product will be listed as free.

To override the global API tab settings for a variable product, tick the Override global checkbox and a settings form will open.

The only other required field is the Software Activation Limit. This field can be left blank for unlimited activations.

If this is not a Subscription product, but you still want to expire API access after a defined period of time, enter the number of days before expiring in the Download Expiry box, otherwise the customer will have API access indefinitely. A subscription allows for there to be a renewal period that can generate a recurring income for customers to continue API access for software updates.

Variable Product Using It's Own Settings
Variable Product Using It’s Own Settings

When the Set API options box is checked, the form that appears allows this product to be configured individually, so Global Settings are overridden.

Order screen settings ↑ Back to Top

API License Key Products
API License Key Products

The API License Key Products meta box has all the information you will need at a glance with the box open or closed. The Activation Limit can changed per API Key. All activations can be disabled for this order by un-ticking the API Access Permission checkbox. The Download Product Permissions can also be deleted further down the Order Screen to disable access to the Upgrade API, but it is better to un-tick the API Access box in case this customer might need access again.

API License Keys are added when an order is first placed. If a line item (product) is added to the order, or if one already exists, API License Keys can be added or deleted. If a line item is added, the page will need to be refreshed, since the pull-down menu to add API Keys is only populated with products that exist for this order on page load.

Options that should never be modified are greyed-out to prevent accidental editing.

The API Key is truncated to make it easy to identify similar API Keys quickly, and can be viewed in full by hovering over an API Key.

API License Key Activations
API License Key Activations

Software versions are updated on the API License Key Activations meta box when client software is activated, and anytime the client software does an update query.

Multisite installations will only show an update version on the activation section of the order screen for the blog domain that runs the blog network. WordPress itself is supposed to perform update queries every 12 hours, but in testing Version updates can take weeks on some blogs, unless the customer clicks Plugins or Dashboard > Updates in the dashboard. Activations can be deleted by the shop manager if needed.

The API Key is truncated to make it easy to identify similar API Keys quickly, and can be viewed in full by hovering over an API Key.

Order Notes Setting
Order Notes Setting

Under WooCommerce > Settings > API Manager license key activation order notes can be configured. The API Manager can then record activations/deactivations by the client software, which is displayed on the Order screen as show below.

Order Screen API Notes
Order Screen API Notes

Up to 100 API License Keys per order can be located using the Search Orders search box.

Shop Order Search
Shop Order Search

Subscription switching ↑ Back to Top

Subscription Switching
Subscription Switching

WooCommerce Subscriptions offers the ability to switch subscriptions, giving subscribers the ability to upgrade/downgrade API Key activations. Since the WooCommerce API Manager provides the ability to sell a single license with multiple activations, this means a subscriber can change the number of activations for example from 1 to 5, or 5 to 15, or they could choose to switch from 15 to 1. When a customer switches subscriptions a new order is created, and a new API License Key will be emailed. The older order API License Key will no longer be valid.

The settings in the screen shot above could be applied to allow for switching subscriptions for products that require the API Manager. These settings are only an example, so modify them to meet your needs.

My API keys ↑ Back to Top

My API Keys
My API Keys

The My API Keys table in the My Account dashboard provides the customer with a list of their products, API License Keys, License Emails, and the number of activations they have remaining. Each activated domain is also displayed for that API License Key, along with a Delete key if the customer needs to remove an activation if their client software is unable to do so, or if perhaps they need to deactivate an activation for software on a blog they have lost access to.

If the WooCommerce Subscriptions extension is active, and if an order is a subscription, it will have a status label in the Subscription column. If the status is active, then that API License Key can be used to access the Update API for software updates, otherwise there is a strikethrough over the API License Key to indicate it cannot be used. If the Subscription is labeled as “No,” then that API License Key belongs to an order that is not a subscription.

If the API Access Permission is revoked on the Order screen for an API Key, or if the subscription is not active, the Activations column will display No Access.

The API Manager will send an error message to the client software if it attempts to activate an API License Key that does not have an API access.

My Account API Key Dashboard Error
My Account API Key Dashboard Error

Although the API Manager is designed to prevent API License Key activations from inactive keys, if an invalid API License Key were activated, it would have an error to inform the customer that the key is invalid.

My API downloads ↑ Back to Top

My API Downloads
My API Downloads

The My API Downloads table in the My Account dashboard provides a link to the product page, the current software version and version date, a link to the changelog and documentation, a download link, and a Save to Dropbox button for easy storage. The download link can only be used once, or it will expire between 5 to 60 minutes after it is generated. If the link is expired it will return an error. The page must be refreshed to regenerate a link with a new expiration.

The changelog and documentation links are set under the API tab of the product edit screen.

WooCommerce API Manager Documentation and Changelog Links
WooCommerce API Manager Documentation and Changelog Links

URL security ↑ Back to Top

Local server URLs that provide access to file downloads are completely secure through the WooCommerce API Manager. URLs expire between 5 to 60 minutes after they are generated, or after the URLis used once. The Update API generates a new URL with each update request. A page URL, like those in the My API Downloads table, must be regenerated by refreshing the page after they expire, or are used once. Each URL contains a signature that corresponds to a hash table, which provides military grade security. A hash class was added in version 1.3.4 that escalates the hashing security depending on the environment version of PHP, so hashes will have stronger security with the most current PHP version.

Remote secure URLS can also be provided through Amazon S3, which expire after a set period of time.

It is recommended to select Remove All Download Links on the API Manager settings page. This will insure your URLS are all generated by the WooCommerce API Manager, and are secure.

WooCommerce API Manager Settings
WooCommerce API Manager Settings

Save to Dropbox ↑ Back to Top

After setting the Dropbox App Key in the API Manager settings, a Save to Dropbox button will appear in the My API Downloads table in the My Account dashboard. This allows customers to easily store their purchase in Dropbox.

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

Save to Dropbox Drop-ins App
Save to Dropbox 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.

Save to Dropbox Drop-ins App Configuration
Save to Dropbox Drop-ins App Configuration

Lost API key form ↑ Back to Top

Lost API Key Menu Link
Lost API Key Menu Link

The WooCommerce API Manager creates a Lost API Key page when the plugin is installed. This provides the option to have a menu link for customers to receive a list of all their API License Keys by email.

Email Lost API Key Form
Email Lost API Key Form

The Lost API Key form only requires the customer email address to make it fast and easy to get the API Key without having to make a support request.

The Lost API Key page can be created manually. Use the following shortcode to display the form.

Client software license form ↑ Back to Top

Client Software LIcense Key Form
Client Software License Key Form

The API Manager plugin example shows an example of a simple form that can be used to activate/deactivate the customer’s software.

Software update screen ↑ Back to Top

Plugin Update Screen
Plugin Update Screen

When client software receives information from the Update API it will display an update screen just as it would appear if the update were from WordPress.org.

View Version Details Screen
View Version Details Screen

The view details link will display a window that has all the options available from the built-in WordPress API. The WooCommerce API Manager uses pages to display the information for these tabs. Any options available in the page editor can be used in this screen, like video embeds, images, etc.

Client software messages ↑ Back to Top

Error Messages

Custom API Error Message
Custom API Error Message
Invalid API Key Error on Software Activation
Invalid API Key Error on Software Activation

The Update API sends informative error messages to notify customers if there is a problem with their software update request, such as when the customer’s update subscription expires. These error messages are a great help when the customer already knows what the problem is when contacting support, or when the customer can resolve the issue on their own.

Activation/Deactivation Messages

Dashboard Activation API Message
Dashboard Activation API Message

The License Key API sends informative activation/deactivation messages to inform the client that their request was successful. For example, the message above informs the client that the plugin was activated, and has 9 out of 15 activations remaining. The activations remaining can also be viewed by the client in their My Account dashboard.

API messages ↑ Back to Top

If the PHP classes that come with the API Manager are used in the client software the following error messages will appear in response to the appropriate event. A successful query to the Update API will return if an update is available or not. A successful query to the License Key API returns a message stating if the software was activated, and how many activations are remaining for that API License Key, which can also be viewed on the My Account dashboard.

Update API Error Messages

Expired License

The license key for {product name} has expired. You can reactivate or purchase a license key from your account dashboard.

Subscription On-hold

The subscription for {product name} is on-hold. You can reactivate the subscription from your account dashboard.

Subscription Cancelled

The subscription for {product name} has been cancelled. You can renew the subscription from your account dashboard.

Subscription Expired

The subscription for {product name} has expired. You can reactivate the subscription from your account dashboard.

Subscription Suspended

The subscription for {product name} has been suspended. You can reactivate the subscription from your account dashboard.

Subscription Pending

The subscription for {product name} is still pending. You can check on the status of the subscription from your account dashboard.

Subscription Trashed

The subscription for {product name} has been placed in the trash and will be deleted soon. You can purchase a new subscription from your account dashboard.

Subscription Not Found

A subscription for {product name} could not be found. You can purchase a subscription from your account dashboard.

API License Key Not Found

A license key for {product name} could not be found. Maybe you forgot to enter a license key when setting up {product name}, or the key was deactivated in your account. You can reactivate or purchase a license key from your account dashboard.

Download Permission/API Access Permission Revoked

Download permission for {product name} has been revoked possibly due to a license key or subscription expiring. You can reactivate or purchase a license key from your account dashboard.

Software Not Activated

{product name} has not been activated. Go to the settings page and enter the license key and license email to activate {product name}.

Switched Subscription

You changed the subscription for {product name}, so you will need to enter your new API License Key in the settings page. The License Key should have arrived in your email inbox, if not you can get it by logging into your account dashboard.

License Key API Messages

API Request that does not contain either “activation” or “deactivation

Invalid API Request

Invalid API License Key

Invalid API License Key.

Client is Using Trial Order or Switch Subscription API License Key to Activate

Invalid API License Key. Login to your My Account page to find a valid API License Key.

Invalid API License Key/Key That Doesn’t Exist

Invalid API License Key. Login to your My Account page to find a valid API License Key. Activation error. No matching API license key exists.

Invalid API License Key/Key That Doesn’t Exist

Invalid API License Key. Login to your My Account page to find a valid API License Key.  Deactivation error. No matching license key exists.

Activation Email and License Key Exist, but No Data in the Database that Matches

No matching API license key exists. Activation error

Order Status Incomplete

Activation error. The purchase matching this product is not complete.

No Downloadable Product Permission

Activation error. There is no download permission for this product purchase.

Software Deactivated

Software has been deactivated.

Software Activation Failed

Activation error. The purchase matching this product is not complete.

No Activations Remaining for License

Exceeded maximum number of activations. Remaining activations is equal to zero.

Invalid Instance/Password

Invalid Instance ID.

Software Activation Failed

Invalid Instance ID. Could not activate API license key.

Software Deactivation Failed

Invalid Instance ID. Deactivation error. No matching instance exists.

No Active Subscription

Subscription Not Active. Could not activate API license key.

A Trial Subscription That Does Not Have Active Status Attempts to Activate

Invalid API License Key. Login to your My Account page to find a valid API License Key.

Invalid Email

Invalid Request. The email provided is invalid. Activation error.

Empty Product ID

Invalid Request. The Product ID was empty. Activation error.

No Activations Remaining

Exceeded maximum number of activations. Remaining activations is equal to zero.

Unique Instance ID Already Activated (Each product must have its own unique Instance ID)

Could not activate API license key.

No API Access Permission (unchecked for this API Key on the Order screen)

This API Key does not have permission to access the Software API.

The Product ID Sent to the API is for a Different Product

This API Key belongs to another product. (Make sure your Software Title, which is the Product ID, is unique for each product.)

Wrong Email Sent for Deactivation

Deactivation error. The email provided is invalid.

Deactivation email and License Key Exist, but No Data in the Database that Matches

Deactivation error. No matching license key exists.

Deactivation Instance ID Does Not Match Activation Instance ID

Deactivation error. No matching instance exists.

API documentation ↑ Back to Top

The examples below use GET requests with properly formatted query strings. POST requests can also be sent to the APIs. Postman can be used test API requests at any time to verify everything is working as expected. Using a local, or staging, server to test a new installation is highly recommended with full debug on to catch errors in your own software, or other software that might cause otherwise hidden issues. The API tries to send responses that can be used identify success or possible issues. The API responses are intended to assist customers to either take their own action to fix the issue, by display those API responses as WordPress messages, or to allow the customer to forward the message to customer support, which can more easily know which problem they need to fix and help the customer faster. The API responses can be very helpful in testing, for example, if the API response is “Activation error. There is no download permission for this product purchase.”, it should be clear what the issue is, and what needs to be done to fix it.

License key API ↑ Back to Top

All requests are listened for on the blog/store domain name with the wc-api endpoint set to am-software-api. The API returns JSON formatted data.

A wp_remote_get query string requires the following parameters.

Activation

* Used to activate software

  • ‘request’ => ‘activation’
  • ’email’ => $email – License email address.
  • ‘licence_key’ => $api_key – API License Key (order_key)
  • ‘product_id’ => $software_title – Product title.
  • ‘platform’ => $domain_name – Blog domain name.
  • ‘instance’ => $password – A unique password generated for each installation.
  • ‘software_version’ => $software_version – The client software version

An activation URL-encoded query string should be formatted like the following example:

The activation filter hook ‘api_manager_extra_software_activation_data’ can used to add the post ID, and all the API Manager order data for the activation, to the JSON data sent to client software. If all the order data is requested it would be formatted as follows:

Here is an example of how this filter hook might be used to return the product SKU to the client software:

Deactivation

*Used to deactivate software

  • ‘request’ => ‘deactivation’
  • ’email’ => $email – License email address.
  • ‘licence_key’ => $api_key – API License Key (order_key)
  • ‘product_id’ => $software_title – Product title.
  • ‘platform’ => $domain_name – Blog domain name.
  • ‘instance’ => $password – A unique password generated for each installation.

A deactivation URL-encoded query string should be formatted like the following example:

Status

*Used to check the activation status of software

  • ‘request’ => ‘status’
  • ’email’ => $email – License email address.
  • ‘licence_key’ => $api_key – API License Key (order_key)
  • ‘product_id’ => $software_title – Product title.
  • ‘platform’ => $domain_name – Blog domain name.
  • ‘instance’ => $password – A unique password generated for each installation.

A status URL-encoded query string should be formatted like the following example:

The status filter hook ‘api_manager_extra_software_status_data’ can used to add the API License Key activation data to the JSON data sent to client software. The data would be formatted as follows:

The ‘status_check’ response will be either ‘active’ or ‘inactive’.

Here is an example of how this filter hook might be used to return the activation data to the client software:

Update API ↑ Back to Top

All requests are listened for on the blog/store domain name with the wc-api endpoint set to upgrade-api. The API returns a serialized stdClass object.

An update, or plugin information, URL-encoded query string would be formatted like the following example:

A wp_remote_get query string requires the following parameters.

Update Check

  • ‘request’ => ‘pluginupdatecheck’
  • ‘plugin_name’ => $slug_name
  • ‘version’ => $slug_name+file_name
  • ‘product_id’ => $software_title
  • ‘api_key’ => $api_license_key – (order_key)
  • ‘activation_email’ => $license_email
  • ‘instance’ => $password
  • ‘domain’ => $domain_name
  • ‘software_version’ => $software_version
  • ‘extra’ => $extra (optional)

Plugin Information

  • ‘request’ => ‘plugininformation’
  • ‘plugin_name’ => $slug_name
  • ‘version’ => $slug_name+file_name
  • ‘product_id’ => $software_title
  • ‘api_key’ => $api_license_key – (order_key)
  • ‘activation_email’ => $license_email
  • ‘instance’ => $password
  • ‘domain’ => $domain_name
  • ‘software_version’ => $software_version
  • ‘extra’ => $extra (optional)

Third party plugins can receive any type of data, and any data type, from client software through the Update API using the following hooks:

  • Filter: api_manager_extra_update_data
  • Action: api_manager_extra_data

The extra data that can be sent using the client’s software is a very powerful feature. Please use it wisely and responsibly.

Amazon S3 integration ↑ Back to Top

The WooCommerce API Manager has built-in core support for the Amazon Simple Storage Service (S3) cloud storage solution. The Amazon S3 integration was accomplished without bloating the extension with large libraries found in the S3 SDK.

Amazon S3 can be used to serve digital downloadable software products rather than serving those same files from the local server. Using Amazon S3 means your files will be download closer, and much faster by the customers, and it will reduce bandwidth costs, as well as load on the local server.

The Amazon S3 URL generated by the API Manager has a configurable expiration time between 5 to 60 minutes, and the URL is completely secure, so even if the link were shared, it will expire. The URL expiration time is set when the URL link is generated. If a download begins before the expiration time limit is reached, the download will continue until complete.

The AWS Secret Access Key is encrypted before it is saved in the database, to insure it cannot be read by anyone, even if your data is stolen from your database.

To setup configure the API Manager to use Amazon S3 go to WooCommerce > Settings > API Manager (tab)

Amazon S3 Settings
Amazon S3 Settings

To create the AWS keys for the first time follow these steps.

If you don’t have an Amazon Web Services account create one so you can use Amazon S3. Now go directly to the Security Credentials page to create your keys by using this link. Click on the Continue to Security Credentials button.

Amazon Web Services Security Credentials

Create your new access key. The key comes paired with a secret key.

Amazon Web Services Security Credentials Create Access Key

Download your rootkey.csv file, which will contain your AWSAccessKeyId and AWSSecretKey, which are the characters after the equal sign.

Amazon Web Services Security Credentials Download Keys

Go to the Amazon S3 dashboard using this link. Create a bucket that will store your files. Folders can be created inside the bucket to help organize files if needed. Upload your downloadable product files.

Click on each file, then on Properties in the top right of the screen. Click on Permissions to expand the menu, then click the X to remove the default permission.

Amazon Web Services Security Credentials Remove File Permissions

Click add more permissions, and choose Authenticated Users, and check only the Open/Download checkbox. This is critical to making sure this link cannot be shared with the world, but will instead required the link generated by the API Manager to securely authenticate access to your downloadable S3 files.

Copy the Link URL that looks like https://s3.amazonaws.com/toddlahman/ame/api-manager-plugin-example.zip, because you will need it for the next step.

Amazon Web Services Security Credentials Set Authenticated Users

 

Note: The proper Amazon S3 URL format must be used. The URL should begin with s3.amazonaws.com, then a subfolder, or subfolders, and then the product filename, for example https://s3.amazonaws.com/toddlahman/example.zip. Otherwise, the API Manager will assume the file is being served from the local server.

Go to Products > General, and Paste the Link URL into the General (tab) > Downloadable Files > File URL, then click Update to save it with your product data. Do this for each product to match it with the Amazon S3 download URL.

WooCommerce API Manager File URL

The API Manager will now serve software updates using Amazon S3, and the links under the customer’s My Account > Available Downloads will be linked to Amazon S3 as well. The local files for the products can now be deleted from the local server, because they will be served from Amazon S3. URLS to Amazon S3 are securely hashed by the API Manager, and set to expire at a set time.

Tip: It is a good idea to keep the file names the same, so you won’t have to change the File URL in the future. If you delete, then upload the product file to Amazon S3, to replace it with your new product/software, make sure to fix the Permissions again.

To create a URL that uses a non-region specific URL like s3.amazonaws.com, rather than a region specific URL like s3-us-west-2.amazonaws.com, these instructions will help.

  1. Create a new bucket. Choose US Standard. This will be a non-region specific URL s3.amazonaws.com.
  2. Create a folder name to store your product file, or just put it in the new bucket. Be sure to follow the file upload instructions so the file will be secure.
  3. Copy and paste the URL into the product Downloadable Files > File URL.
  4. Test the download URL from the My Account dashboard. The URL will be securely hashed by the API Manager.

non-region specific Amazon S3 bucket

Troubleshooting ↑ Back to Top

It is best to create a callback function for the register_deactivation_hook to delete the data required for the License Key API, and to deactivate the software. This gives the customer the ability to fix some issues on their own without assistance, and it provides a tool for technical support to get the software reactivated after some sort of event on the client’s server.

If a client had a disaster occur on their server, and the software were not deactivated properly, go to WooCommerce -> Orders -> API License Key Activations, and click the Delete button next to the customer domain. This will allow the client to reactivate, but the register_deactivation_hook routine described above can solve other related reactivation issues. The customer can also delete the software activation from their My Account dashboard, eliminating the need to contact support to perform this function.

Invalid request error ↑ Back to Top

Usually the “Invalid Request” request is returned with additional information. If only “Invalid Request” is returned, then it is sent because you have a critical error that can’t otherwise be determined, and revealed in the error. There are several reason for this error:

  1. The person making the purchase should have a “customer” or “subscriber” role. Be sure to create a test account with one of these roles, then logout, and make the purchase as that person. Also, guest users cannot make purchases, because the API Manager needs an account, and an order, to determine if the customer has access to the requested resources.

Overriding templates ↑ Back to Top

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

SkyVerge answered quite a few questions for people having trouble figuring out how to accomplish a template override with their theme, which can be found here.

Back to the top