WooCommerce Authentication, Database Structure & Limits

Authentication

API Docs : https://woocommerce.github.io/woocommerce-rest-api-docs/wp-api-v2.html?shell#authentication

WooCommerce offers a simple basic auth which consists of API keys (client key and client secret) and there are two ways of obtaining those API keys:

• The first one is via the WooCommerce interface where the user can generate the keys manually
• The second is via auto generating API keys using an application authentication endpoint in which the user approves our “app” and is then we receive and store the keys via callbacks. This method is not like the standard where we need the ecommerce provider to install an app, for WooCommerce each store can connect to our integration without the need of having an app (as there are no apps since WooCommerce itself is an app for WordPress).

We will go with the second method as it is very easy to implement, we just need to build a link which will get sent to the user’s email and then when they click it they will grant us access to their APIs. In this link we need to provide a callbacks url where WooCommerce will push the api keys

Example how to build an authentication URL :

<?php
$store_url = 'http://example.com';
$endpoint = '/wc-auth/v1/authorize';
$params = [
    'app_name' => 'My App Name',
    'scope' => 'write',
    'user_id' => 123,
    'return_url' => 'http://app.com',
    'callback_url' => 'https://app.com'
];
$query_string = http_build_query( $params );

echo $store_url . $endpoint . '?' . $query_string;
?>

Authentication URL Mapping :

”User ID in your APP. For your internal reference, used when the user is redirected back to your APP. NOT THE USER ID IN WOOCOMMERCE” We want to use the MCPro channel ID here in order to understand which account we will get the callback response for. | | | return_url | | I suggest we use https://www.threecolts.com/multichannel-pro | | | callback_url | | We need to use our callbacks machine url here , as we will receive a consumer_key and consumer_secret which we need to store into Channel WooCommerce (as mentioned below in the Database Structure section) |

So an example authentication URL should look as follows : https://ecom-delicately-vibrant-shark.wpcomstaging.com/wc-auth/v1/authorize?app_name=MultichannelPro&scope=read_write&user_id=123&return_url=https://www.threecolts.com/multichannel-pro&callback_url=https://callbacks-new.wearepentagon.com/

❗Note : This link was not tested as I do not have proper callback url so this needs to be tested during develpoment.

Things to keep in mind when setting the callback_url

1. Non HTTPS URL endpoints are not allowed.
2. URL should not be a localhost url (e.g localhost/callback would give an invalid URL error)
3. URL should not contain port number (e.g localhost:4320/callback or foo.bar.dev:4892/callback are invalid)
4. Callback URL should be a POST url

Example callback response :

{
    "key_id": 1,
    "user_id": 123,
    "consumer_key": "ck_xxxxxxxxxxxxxxxx",
    "consumer_secret": "cs_xxxxxxxxxxxxxxxx",
    "key_permissions": "read_write"
}

Mapping :

Database Structure

We will need the standard tables such as Channel WooCommerce Order WooCommerce and Listings WooCommerce. The Order WooCommerce and Listings WooCommerce will not be added here, instead in the other parts of the scope wherever needed, the tables and the new fields will be specified.

Channel WooCommerce: This is our starting point and this table will keep the integration settings.

We display as “Write” but send as “write” We display as “Read” but send as “read” We display as “Read & Write” but we send as “read_write” | Read & Write | | consumer_key | varchar | No | This field should be hidden in the UI. It is only to be visible in the backend. This is the fied that we need to store the key from the bacllbacks and we need this for the authentication with every call. | N/A | | consumer_secret | varchar | No | This field should be hidden in the UI. It is only to be visible in the backend. This is the fied that we need to store the secret from the bacllbacks and we need this for the authentication with every call. | N/A | | key_id | varchar | No | This field should be hidden in the UI. It doesn’t seem we will need this, but we receive it with the callbacks response so we might as well just store it. | N/A | | Default Courier | dropdown | No | This should be an enum dropdown table with all available couriers. More info can be found in the [WooCommerce Ship Orders (through Shipment Tracking plugin)](WooCommerce%20Order%20Management%201ee047df7a8180ef986cd0325d0f086a/WooCommerce%20Ship%20Orders%20(through%20Shipment%20Tracking%201f3047df7a8180c5b2f2cf129da67fd2.md) scope. | | | Product Status for Get Products | dropdown | No | Should have few options : draft, pending, private , publish and any. We want to keep them with capital first letter displayed, but send them in lowercase to Woo. | publish |

Limits

There are no specific API Limits in the WooCommerce documentation. But it is recommended that we don’t exceed 100 requests per minute.

Pagination

Requests that return multiple items will be paginated to 10 items by default. This default can be changed by the site administrator by changing the posts_per_page option. Alternatively the items per page can be specified with the ?per_page parameter:

GET /orders?per_page=15

We can specify further pages with the ?page parameter:

GET /orders?page=2

We may also specify the offset from the first resource using the ?offset parameter:

GET /orders?offset=5

Page number is 1-based and omitting the ?page parameter will return the first page.

The total number of resources and pages are always included in the X-WP-Total and X-WP-TotalPages HTTP headers.

If there are changes in the default pagination, it will be explicitly mentioned in the different scopes.