Setting up Demfilz ABN Lookup

1. Install and activate

Upload demfilz-abn-lookup-for-woocommerce.zip under Plugins → Add New Plugin → Upload Plugin and activate it. WooCommerce must be installed and active (WooCommerce 9.9 or later, WordPress 6.3 or later, PHP 7.4 or later); if it is not, a line under the plugin on the Plugins screen says so. The plugin adds an ABN field to the checkout, an ABN Lookup tab under WooCommerce → Settings with a Settings section and a Lookup tool section, and an ABN check panel on the order screen.

Nothing else is needed to start. The ABN field is live at once: optional, for customers with an Australian billing address, with the check digit test.

2. The ABN field at checkout

Where	What the customer gets
Checkout block	The ABN field under the email address, in Contact information. It reads "ABN (optional)" while it is optional.
Classic checkout	The ABN field after Company, in the billing details. A valid number is tidied to the usual 51 824 753 556 spacing when the customer leaves the field.
My Account → Account details	Returning customers get their saved ABN filled in at checkout and can change it here. An invalid ABN is refused here too.
Other billing countries	With the default "Customers with an Australian billing address", the field is hidden for other countries and nothing is checked or saved.

A line under the field answers while the customer types:

The customer sees	When
"An ABN has 11 digits."	They leave the field with fewer than 11 digits.
"That is not a valid ABN. Please check the 11 digits."	The check digits do not add up. Shown at once, and nothing is sent to the register.
"This ABN has a valid format."	The check digits add up and ABNs are not being looked up: no GUID is saved, or you chose to check the format only.
"ACME PTY LTD. Active ABN, registered for GST."	The register holds an active ABN with this number (or "not registered for GST"). The name is the one the register holds for the ABN.
"This ABN is cancelled on the Australian Business Register. Please check the number."	The ABN is cancelled. The order is refused only if you chose to refuse cancelled ABNs.
"We could not find this ABN on the Australian Business Register. Please check the number."	The register holds no ABN with this number. Refused only if you chose to refuse.
"This ABN is not registered for GST."	Only with the GST rule ticked.
"We could not check this ABN right now. You can still place your order."	The register could not be reached, did not accept your GUID, or an hourly allowance is used up. The order goes through.

When the register returns a business name and the Company field is empty, the Company field is filled in. A name the customer typed is never replaced.

3. Get your free ABN Lookup GUID

To look ABNs up, the Australian Business Register needs to know who is asking. Registration is free: go to ABN Lookup web services, register and accept the web services agreement, and the register emails you a GUID, a code like 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d. It is not always instant. Until you paste it in, the field works with the check digit test.

Paste the GUID into ABN Lookup GUID under WooCommerce → Settings → ABN Lookup and save. A notice above the field then tells you where you stand:

Notice	What it means
"Connected to the Australian Business Register. ABNs are looked up as customers enter them."	The register accepted your GUID and lookups are on.
"No GUID is saved."	ABNs are checked for a valid format only: a mistyped or made-up number is refused, but a cancelled ABN is not noticed.
"Your GUID works, but lookups are switched off"	"When an ABN is entered" is set to check the format only.
"The Australian Business Register did not accept this GUID."	Check that it matches the one in your registration email. Until it is fixed, ABNs are checked for a valid format only and orders are not held up.
"The Australian Business Register could not be reached just now."	The checkout keeps working: ABNs are checked for a valid format and orders are marked "not checked" until the register answers again.

A GUID has 32 letters and digits in five groups. If what you paste does not look like one, it is not saved, and the GUID you had before stays in place. To show whether your GUID works, the settings page looks up the Australian Taxation Office's own ABN and remembers the answer for 12 hours, or for 5 minutes after a failure.

What is sent to the register. Nothing, until you have saved a GUID. With one, requests go from your server to abr.business.gov.au and carry the ABN, ACN or business name being looked up, and your GUID. Nothing else: no customer name, email address, postal address, IP address or order details. Your GUID is kept on your server and is never sent to your customers' browsers. The register's terms are its web services agreement and its privacy policies.

4. WooCommerce → Settings → ABN Lookup

The ABN Lookup tab has two sections, linked across the top: Settings and Lookup tool. These are the settings.

Checkout field

Setting	What it does
ABN field	Optional (default), Required when a company name is given, Required or Do not ask for an ABN. "Required when a company name is given" suits stores with both trade and retail customers: people who fill in Company must give an ABN, everyone else can leave it empty. The Company field has to be shown in your checkout for this.
Ask	Customers with an Australian billing address (default) or All customers. For other billing countries the field is hidden and nothing is checked.
Label	Empty shows "ABN".
Company name	On by default. Fill an empty Company field with the business name the register returns. Needs a GUID.
Billing address	Off by default. Add the ABN as the last line of the order's billing address. The address is what order emails and most PDF invoice and packing slip plugins print, so this puts the buyer's ABN on those documents.

Australian Business Register

Setting	What it does
ABN Lookup GUID	Your GUID from the register. Kept on your server; it is never sent to your customers' browsers.
When an ABN is entered	Look it up, and refuse ABNs that are cancelled or not on the register (default), Look it up and keep the answer with the order, but refuse nothing, or Check the format only (no lookup). An ABN with the wrong check digits is always refused. Without a GUID only the format can be checked, whatever is chosen here.
GST	Off by default. Treat an ABN that is not registered for GST like a cancelled one.
Keep answers for	The hours before the same ABN is looked up again: 24 by default, from 1 to 720.

Data

Setting	What it does
Uninstall	Off by default. Delete these settings when the plugin is deleted. ABNs on orders and customer accounts are always kept.

5. What happens when an ABN is entered

The ABN	What happens
Has the wrong check digits	Always refused, in both checkouts and in My Account. No request is made.
Is active	Accepted. The entity name, entity type, GST registration, state and postcode are kept with the order.
Is cancelled, or not on the register	With "refuse" chosen, the customer sees the reason under the field and when they try to place the order, and the order is refused. With "refuse nothing" chosen, the order is accepted and the result is shown on the order.
Is not registered for GST	With the GST rule ticked, treated like a cancelled ABN. Otherwise accepted, and the order shows it.
Cannot be checked	The register could not be reached, did not accept your GUID, or an hourly allowance is used up: the order goes through and is marked "Not checked" with the reason.

The ABN is checked again on your server when the order is placed, whatever the browser sent. An ABN never changes tax: in Australia an ABN does not make a sale GST-free, so the ABN is for your records, your tax invoices and your trade terms.

6. The ABN on the order

Where	What
Order screen	The ABN among the billing details, where you can edit it, and an ABN check panel: status, entity name, entity type, GST registration, state and postcode, when it was checked and a link to the public ABN Lookup record.
Check again	Asks the register afresh, without the remembered answer, and shows the result in the panel.
Editing the ABN	Change it and save the order: the old check is dropped and a new one is made. If what you type is not a number, it is not saved and an order note says so.
New order email to you	A line with what the register answered, for example "Active, ACME PTY LTD, registered for GST".
Order emails and order pages	The ABN on the order received and View order pages and in order emails, under Additional information, or in the billing address when that setting is on.
Order search	Type an ABN in the order search to find its orders.
Orders from the REST API	Orders created through the REST API with _billing_abn in their meta are tidied and checked too.

The panel reads Active, Cancelled, Not on the register, Valid format, not looked up (no GUID, or format only) or Not checked (with the reason).

Tax invoices. A tax invoice for a sale of $1,000 or more has to show the buyer's identity or ABN. Tick "Add the ABN as the last line of the order's billing address" and the ABN is printed wherever the billing address is, which covers order emails and most PDF invoice plugins. Check a sample invoice from your own invoice plugin after switching it on.

7. The lookup tool

Open WooCommerce → Settings → ABN Lookup → Lookup tool, type an ABN (11 digits), an ACN (9 digits) or part of a business name, and click Look up. The answer comes straight from the Australian Business Register and is not saved anywhere. For an ABN or an ACN you get the record: status, entity name, entity type, GST registration and main business location, plus business names and the ACN where the register holds them, with a link to the public record. A name gives up to 10 of the closest matches; choose one to see its record. Without a GUID the tool tells you what is missing, and an ABN still gets its format check.

8. The limits that protect your GUID

Limit	What it does
Check digits first	A number that fails the check digit test is never sent to the register.
Remembered answers	Each ABN is asked about once per cache period, 24 hours by default.
Live lookups	20 an hour per IP address and 300 an hour across all visitors.
Lookups when an order is placed	An allowance of their own, 300 new ABNs an hour, so a visitor who uses up the live lookups cannot switch off the check on orders.
When an allowance is used up	The ABN is marked "not checked" on the order, where you can check it again.
After a failed request	The plugin waits a minute before trying again, so a slow register does not slow your checkout.
After a rejected GUID	Lookups pause for 10 minutes and the settings page says so. The checkout is not affected.

The limits can be changed with the dabn_rate_limit, dabn_rate_limit_site and dabn_rate_limit_orders filters.

9. Privacy and Trade Accounts

The ABN and its check are included in WooCommerce's personal data export and erasure, and the plugin adds suggested wording for stores that ask for an ABN to WordPress's privacy policy guide. If you use Demfilz Trade Accounts for WooCommerce, the trade account screen shows what the register says about the ABN the applicant gave.

10. For developers

Function or hook	Use
dabn_is_valid_abn(), dabn_format_abn()	Whether a value is a well-formed ABN (11 digits with valid check digits, without asking the register), and an ABN the way it is written: 51 824 753 556.
dabn_lookup_abn()	Look an ABN up on the register. Cached, and it needs the store's GUID.
dabn_get_order_abn(), dabn_get_order_abn_check(), dabn_get_customer_abn()	The ABN of an order, what the register answered for it, and the ABN saved on a customer account.
dabn_check, dabn_lookup_result	Filters: the outcome of checking an ABN, and the record read from the register.
dabn_block_field, dabn_classic_field	Filters: the field in the checkout block and in the classic checkout.
dabn_rate_limit, dabn_rate_limit_site, dabn_rate_limit_orders, dabn_request_args	Filters: the three hourly allowances, and the arguments of the request to the register.
dabn_order_synced	Action, after an order's ABN has been tidied and checked.

Order meta: _billing_abn (11 digits) and _dabn_check (an array: abn, result, name, type, code, names, gst, since, state, postcode, acn, checked, note, order). Customer meta: billing_abn. These are the names WooCommerce itself uses for a billing field called billing_abn, so stores that already collect an ABN in a field of that name keep their data.

Troubleshooting

The ABN field does not show: by default it is only for customers with an Australian billing address, so it is hidden once another billing country is chosen. Check that ABN field is not set to "Do not ask for an ABN". In the checkout block the field is under the email address; in the classic checkout it is after Company.

An order says "Not checked": the register could not be reached, did not accept your GUID, or an hourly allowance was used up, and the panel says which. The order was let through on purpose. Click Check again on the order when you are ready.

An order says "Valid format, not looked up": no GUID is saved, or "When an ABN is entered" is set to "Check the format only (no lookup)". The number could be an ABN, but nobody has asked the register whether it has been issued or is still active.

The register does not accept my GUID: check that it matches the one in your registration email. A GUID has 32 letters and digits in five groups; one that does not look right is not saved, and the GUID you had before stays in place. Until it is fixed, ABNs are checked for a valid format only and orders are not held up.

"Required when a company name is given" does not ask for an ABN: the Company field has to be shown in your checkout for this.

The ABN is asked for twice: you already collect ABNs in a custom checkout field. If that field is called billing_abn, the plugin uses the same order meta and customer meta, so nothing is lost: remove the old field so it is not shown twice.

What happens if I remove the plugin: ABNs stay on your orders and customer accounts. Cached register answers are deleted; the settings are deleted only if you tick the Uninstall box.