order-fetcher

Retrieves WooComerce line-item order information and displays it in your terminal or saves it as a CSV file.

Purpose

This tool is intended to help in cases where line-item order information needs to be collated/managed per-sku, rather than per-order. For example, one dog club uses a WordPress/WooCommerce site to collect orders for things related to a dog show, and each "thing" is handled by a different person. They use order-fetcher with the --sku and --sku-prefix flags to extract the details on a product-by-product basis, and disseminate that information to the appropriate person.

Getting started

After installing order-fetcher (via npm install -g order-fetcher), you can run orders config init to create your initial configuration file. It will ask a bunch of questions to help get everything set up. You will need to make sure that the WooCommerce API is enabled, and that you have a key and secret defined. Because order-fetcher only ever retrieves data, and never makes changes to your site, it only requires read-only access.

The nickname you give your site allows you to disambiguate if you have more than one: orders host1 ... and orders host2 ... will retrieve data from either “host1” or “host2”, assuming those are the nicknames you gave. (But please, for your own sanity, use useful and memorable nicknames!)

If you don’t have too many historical orders on your site, your first request can be as simple as orders host1. If you have a lot of orders, however, that command can take a while. Using the --after option to only include orders on-or-after a particular date (like orders host1 --after 2019-07-01) can dramatically improve performance.

Usage

When all else fails, orders --help (or order-fetcher --help) lists all of the available options.

Top-level commands/options

command	description
config	shows configuration information
get (or host nickname)	retrieves orders from a WooCommerce site
-v, --verbose	increase verbosity of logging output, can be given multiple times
-h, --help	output usage information
--version	output the version number

config commands/options

option	description
init	interactive first-time configuration set up
view	show current configuration
add [host-nickname]	add a new WooCommerce host (interactive, like init)
remove [host-nickname]	remove an existing WooCommerce host
timezone (or tz) [zone]	change the timezone (interactive if zone is not provided)
-h, --help	output usage information

get (or host-nickname) options

option	description
--host host-nickname	WooCommerce host to use (only for orders get, not needed when using a nickname directly)
--after date	include only orders after the date
--before date	include only orders before the date
--status status	include only orders with the given status
--sku sku	filter to the specific sku, can be given multiple times (default: )
--sku-prefix skuPrefix	filter to the sku prefix, can be given multiple times (default: )
--list-skus	list the skus found in the orders
--list-statuses	list the statuses found in the orders
--list-columns	list the available columns found in the items
--omit-blanks	omits columns where every item's value is blank or missing
--omit-identical	omits columns where every item's value is identical
--omit-payment	omits payment columns (including payer address and phone)
--omit column	omits a specific column
--include column	includes a specific column
--columns column-list	selects an exact set of columns to display (comma-separated names, use \, to include a comma in a column name)
-o, --out filename	file to write (CSV format)

Best practices

For WooCommerce installations with a large number of historical orders, making use of the --after options is highly recommended. Similarly, use --status processing to only include orders that haven't been handled yet. (And then mark those orders as "completed" as soon as you deal with them.)

When generating CSV output, the columns come directly from the item information in WooCommerce. More than likely, you'll want to use the --sku option to create CSV files on a sku-by-sku basis.

About column filtering

The various --omit... and --include options control whether columns are included or omitted in the output. As a rule of thumb, columns are included for CSV file output for consistency across invocations, and the --omit-... options are enabled by default for screen output to reduce line-wrapping. If you need to not omit columns for screen output, you can prefix the option with no, as in --no-omit-identical.

If the --omit-... options are too coarse, you can enable or disable individual columns using the --include and --omit options, or for complete control use the --columns option to specify exactly what columns you want displayed and in what order they will appear. Using --list-columns will list all of the columns present in a given set of items. Do note that unless you use --columns to specify an exact set, the following columns are always included: "order#", "date", "name", "email", "qty", and "total".

The --columns option also allows for columns/fields with commas in the name by backslash-escaping the comma, as\,such. You can also provide column aliases if you need to rename the output column using the alias=real_name syntax. Additionally, you can prefix a column/field with [date] to attempt to parse unix timestamps and format the values as dates.

Examples

orders host1 --after 2019-01-01 --status processing --list-skus

Retrieve all order line-items after 1 January 2019 (inclusive) with a status of "processing", and list the unique SKUs. This is useful as a precursor to creating per-SKU CSV files.

orders host1 --after 2019-01-01 --status processing --sku some-sku --out some-sku.csv

Retrieve all order line-items as in the previous command, filter the items to the sku some-sku, and write to 'some-sku.csv'.

orders host1 --sku-prefix some-sku --list-columns

Retrieve all order line-items with a sku that starts with some-sku, and list the available columns.

orders host1 --after 2019-01-01 --sku-prefix some-sku --columns "name,email,image" --out some-sku.csv

Retrieve all order line-items with a sku that starts with some-sku, and write only the "name", "email", and "image" columns and to 'some-sku.csv'

orders host1 --after 2019-01-01 --sku some-sku --columns "name,count=qty" --out some-sku.csv

Retrieve all order line-items with the sku some-sku and write the column "name" and the "qty" column with the label "count" to 'some-sku.csv'