Besides collecting shopper selections and information, what does a shopping cart do? It reports the gathered data to the merchant, of course! Hazel is no different in this respect, except that she allows you to fully customize these order reports.
Once a customer submits a
FINISH action of some sort, Hazel performs several actions. Here they are, roughly in the order they are performed by Hazel as of Hazel version 3.405.
Before discussing each of those steps, let's go over some basics of order identification. Specifically, the order-id.
The Order ID
ORDER_ID is set by Hazel the first time someone reaches the
CONFIRM stage of an order. This is the point when they have submitted all their billing and shipping info to Hazel, usually right after the
By default, the
ORDER_ID looks something like
20010510155600-12345678. That's the date followed by the random client-id assigned to the shopper. You can modify this format quite simply by editing the
ORDER_ID_FORMAT field value in your hazel.config file.
ORDER_ID_FORMAT can be any text, but you'll want to use some HZML tokens in there unless you want every damned order to have the same order-id. It is set internally to the default
"%HZH_DATE-%HZE_CLIENT" to mimic the old style.
In addition to the usual HZML tokens, the format has a special
%HZH_ORDER_SEQ token available. The "order sequence" is a serial number incremented each time a shopper has an order-id assigned. Thus, this number will never be re-used.
If you'd like to start the order sequence at a particular number, you can set
MIN_ORDER_SEQ in your hazel.config to that number, and Hazel will use it if greater than the recorded number. You can also reset the order sequence manually by editing the
hazel-cat/users/orderseq.txt file, changing the number in its first line--just be sure to enter a number only!
Here are some sample values for your hazel.config:
## This one will just use a number, such as "8"
## This one would use your STORE_NAME field, postfixed with (eg.) "-8"
## Using the fixed-width HZML token format, this would display as "00000008"
## Start the order sequence at 100000. This might be useful if you have
## multiple stores, and wanted to start each one at a specific number. You
## could set the next store to 200000, next at 300000, etc.
The Orders File
ORDERS_DB hazel.config file value tells her where to write a record of her orders. Each order record is described by your
hazel-cat/templates/order_format.txt template. You can customize it as you like, but the default behaviour will be to just slap that baby onto the end of the file.
Alternate orders "db" formats are available. One is the "tabs" format. Specify
ORDERS_DB_FORMAT:tabs in hazel.config and Hazel will regard each line of
order_format.txt as a tab-delimited record to append to the orders file. Useful if you're importing to a database or accounting program.
Another useful format is
ORDERS_DB_FORMAT:file. Set that, then create a
hazel-cat/orders directory, and instead of appending the rendered result of the order format template to the orders file, she'll write it as a file named
orderid.txt in that orders directory. This is arguably better than a single file, as you can download and delete individual orders as you process them.
Sometimes a merchant will want to perform some extra special actions for a shopper who's purchased a product, such as a serial number or activation key, adding them to a mailing list, etc.
This can be accomplished by the hacker-types by writing a script to perform the actions (conforming to Hazel's API), placing that script in the same directory as Hazel (the
CGI_DIR directory in your hazel.config), then giving the script name as the value of
MY_FINISH in hazel.config.
As one might surmise from reading the API docs, these types of actions are best performed by someone accustomed to programming.
The receipt page is the final page served by Hazel to a shopper. It can be fully customized just as any other template. It is located in
As of Hazel 3.378, Hazel breaks with her usual expiration rules on the receipt page, and instead allows it to expire in 300 seconds (5 minutes.) This prevents certain inadequate browsers from reloading the final page to (eg.) print an order, which could cause the shopper to see a confusing message from Hazel. You can modify the expire period by setting a number of seconds as the value of
HTTP_RECEIPT_EXPIRES in hazel.config.
The Store Invoice
The store invoice is described by the
hazel-cat/templates/store_invoice.txt template. Its text is emailed to the recipients specified by the
ORDER_RECIPIENTS field in your hazel.config file.
As of Hazel version 3.340, you can fully customize the headers of email she sends (store invoice, shopper invoice) by adding
REPLACE_EMAIL_HEADERS:1 to your hazel.config. Hazel will interpret all lines up to the first blank line in an email template as headers to be passed to your mail agent. (Be sure to start templates without any custom headers with a blank line.)
The Shopper Invoice
The shopper invoice is described by the
hazel-cat/templates/shopper_invoice.txt template. Its text is emailed to whatever address was specified by the shopper in the
BILL_EMAIL field during checkout.