=== CSV Exporter for Australia Post ===
Contributors: bloodweb
Tags: woocommerce, shipping, australia post, csv, export
Requires at least: 5.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 4.1.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Turn selected WooCommerce orders into native Australia Post Domestic and International bulk shipping CSVs, straight from the Orders screen.

== Description ==

Tick the orders you want to ship, choose **Export AusPost manifest** from the
Bulk actions dropdown, and download a CSV that Australia Post's bulk shipping
tool accepts as-is. Orders are split by destination automatically, so you get a
Domestic file, an International file, or both, with no reformatting and no
retyping addresses.

The plugin is free and sends nothing anywhere. It reads your orders and writes
a file.

= Built around what Australia Post actually rejects =

Getting the columns right is the easy half. Most of the work in this plugin is
in the values, because the importer refuses a file for reasons it explains
badly:

* **Whole-centimetre dimensions.** Australia Post rejects any dimension with
  more than 4 integral digits or more than one decimal place, which a
  calculated measurement such as 9.18 or 13.65 trips instantly.
* **Item weight never below the declared contents.** On international
  manifests each content line is rounded up to the 0.001 kg floor, so a parcel
  of many sub-gram pieces can declare more across its contents than the order
  weighs. That is rejected with "the input shipment request is invalid for item
  content weight". The exported weight is always the larger of the two.
* **Customs values of at least 1.** Free lines and fully discounted lines would
  otherwise trigger "Parcel Contents - Value is in error".
* **Minimal quoting.** PHP's own CSV writer quotes any field containing a
  space, which produces a header row Australia Post cannot match against its
  required column names. This plugin quotes a field only when the value truly
  needs it.
* **The Schedule 8 declaration.** Australia Post requires every domestic parcel
  to state whether it contains Schedule 8 or medicinal cannabis. Leave the
  column out and the upload still succeeds, but MyPost asks for the answer
  again the moment you open an order to edit it, one order at a time.

= Package size that reflects what is in the box =

Rather than stacking every item, products are packed into your configured
parcel footprint: each product's volume is totalled, divided by a configurable
packing efficiency to allow for air between items, and spread across the base
area. A satchel of thirty flat pieces no longer exports as thirty layers deep.

The parcel is also never shallower than the bulkiest single item it has to
contain, measured in its best-fitting orientation. Dimensions and weights are
converted from your store's own units, so a shop measuring in millimetres or
grams still exports correct centimetres and kilograms.

= Signature on delivery, resolved in three steps =

1. The customer's own choice, read from the order and from the order's shipping
   line, so a flag attached to the chosen shipping method is picked up either
   way.
2. Any shipping method you list as requiring a signature, for services where
   the signature is a property of the rate rather than a customer choice.
3. Your configured default.

= Pro add-on =

[CSV Exporter Pro](https://bloodweb.net/plugins/csv-exporter-pro-for-australia-post/)
is a separate, paid add-on for stores that need more: customs descriptions and
HS codes per product, variation or category (including 10-digit US codes),
marking orders as exported with a warning before a duplicate upload, and
importing tracking numbers back onto orders from a CSV. Everything
described above stays in this free plugin.

= For developers =

Filters: `apcsv_content_line` (one customs content line, with its item, product
and order), `apcsv_order_description`, `apcsv_order_edn`, `apcsv_customs_missing`,
`apcsv_delivery_address`, `apcsv_order_signature` and
`apcsv_signature_meta_keys`. Actions: `apcsv_export_ready` (the export notice is
about to show) and `apcsv_exported` (a manifest was written).

= Links =

* [Plugin page and version history](https://bloodweb.net/plugins/csv-exporter-for-australia-post/) at bloodweb.net, including downloadable sample manifests
* [Full documentation](https://bloodweb.net/plugins/csv-exporter-for-australia-post/readme)
* [Jack Ewers](https://jackewers.com/), who builds it

= Privacy =

This plugin makes no external requests. It does not phone home, check for
updates from anywhere but WordPress.org, load remote scripts, or transmit order
data to any third party. The CSV is built on your own server and sent straight
to your browser as a download.

= Not affiliated with Australia Post =

This is an independent plugin. It is not made, endorsed or supported by
Australia Post. "Australia Post" and "AusPost" are trademarks of the Australian
Postal Corporation and are used here only to describe what the plugin is
compatible with.

== Installation ==

1. Install and activate the plugin. WooCommerce must be active.
2. Go to **WooCommerce > Settings > Shipping > AusPost CSV Exporter**.
3. Fill in your sender ("Send From") details. These are deliberately empty on a
   fresh install, and the export refuses to run until Name, Address Line 1,
   Suburb, State and Postcode are set, rather than producing a manifest with no
   return address.
4. Set your package defaults: description, parcel length and width, minimum
   height, packing efficiency and fallback weight.
5. If you ship internationally, set your customs defaults: item description,
   HS tariff code, Export Declaration Number, reason for export and country of
   origin. These are also empty on a fresh install, and international exports
   wait until the item description, HS tariff code and EDN are set. Domestic
   exports are not held up.

To export, go to **WooCommerce > Orders**, tick some orders, choose **Export
AusPost manifest** from Bulk actions and click Apply. A notice appears with a
download button for each manifest that applies. To export a single order, open
it and choose the same entry from the **Order actions** box.

== Frequently Asked Questions ==

= Do I need a paid Australia Post account? =

You need whatever account you already use for bulk lodgement, typically MyPost
Business. The plugin produces the file; it does not talk to Australia Post.

= Why is the export refusing to run? =

Your sender details are not set. A manifest with no return address is rejected
on upload, which you would only discover after switching tabs and trying to
lodge, so the plugin stops earlier and links you to the settings screen.

If only the International download is missing, your customs details are not
set. Every customs declaration needs an item description, an HS tariff code and
an Export Declaration Number, and no default is true for every store.

= What HS tariff code should I use? =

The one that describes what you sell. There is no general-purpose code. Parcels
to the United States need the full 10-digit code; Australia Post returns
US-bound parcels carrying 6 or 8 digits. The same code written with dots, for
example 7117.90.00, is accepted in the Export Declaration Number column.

= Can I send Schedule 8 or medicinal cannabis? =

Not through bulk import. Australia Post rejects any bulk import declaring Yes,
and those parcels need a StarTrack account instead. The setting exists so the
plugin never makes a declaration on your behalf that is not true.

= My store measures in grams and millimetres. Does that work? =

Yes. Product dimensions and weights are converted from your store's units under
WooCommerce > Settings > Products.

= Where does the package height come from? =

It is calculated, not guessed. See the Description above for how packing
efficiency and the containing-height check work. The exported height is never
below the minimum you configure.

= Does it support HPOS? =

Yes. The plugin declares compatibility with High-Performance Order Storage and
registers its actions on both the classic and HPOS order screens.

== Screenshots ==

1. The Export AusPost manifest bulk action on the WooCommerce Orders screen.
2. The download notice, offering a Domestic and an International manifest.
3. The settings screen under WooCommerce > Settings > Shipping.
4. A domestic manifest opened in a spreadsheet.

== Changelog ==

= 4.1.1 =
* Readme: describes the Pro add-on's tracking import accurately.

= 4.1.0 =
* Hooks for add-ons: per-line customs values, the parcel description, the
  EDN, the customs check, and actions when an export is ready and when a
  manifest is written.
* A link to the optional Pro add-on in the settings footer and on the Plugins
  screen, hidden once the add-on is installed.

= 4.0.2 =
* International exports now wait until the item description, HS tariff code
  and Export Declaration Number are set. Fresh installs no longer default to
  one store's jewellery customs values. Domestic exports are unaffected.
* The default domestic delivery service is now STD.
* Error messages are translatable, and the plugin passes WordPress.org's
  Plugin Check.
* Tested against WooCommerce 11.1.

= 4.0.1 =
* Added documentation, plugin page and author links to the Plugins screen and
  the foot of the settings screen.

= 4.0.0 =
* Renamed to CSV Exporter for Australia Post for the WordPress.org directory.
  Existing settings are kept: the internal option prefix is unchanged.
* Added the Schedule 8 / medicinal cannabis declaration to domestic manifests,
  so MyPost stops asking for it order by order after an import.
* Renamed the bulk action to "Export AusPost manifest".
* Tested against WordPress 7.1 and declared WooCommerce as a required plugin.

= 3.0.0 =
* Renamed every function, option, hook and filter to the apcsv_ prefix.
  Settings are migrated automatically on first load.
* Signature on delivery now also reads the order's shipping line, and any
  shipping method marked as signature-required.
* Orders with no shipping address fall back to the billing address as a whole,
  instead of exporting blank recipient columns.
* Fixed a fatal error on WooCommerce below 5.6, where get_shipping_phone() does
  not exist.
* Fixed an unticked signature checkbox reading as "no choice made" and falling
  through to the store default.

= 2.6.0 =
* Australia Post's reworked CN23 categories, keeping B2B and B2C sales apart.
  Values saved under the old list are migrated on read.

= 2.5.0 =
* Export a single order from its Order actions box.
* Sender details are no longer pre-filled with another business's address, and
  the export stops until yours are set.

= 2.4.0 =
* Parcel height always clears the bulkiest product in the order.
* Customs values of at least 1, and parcel weight that always covers the
  contents it declares.

= 2.3.0 =
* Volumetric package height with configurable packing efficiency.

= 2.2.0 =
* Whole-centimetre dimensions, fixing "Item Height is in error" on upload.
* Dimensions and weights converted from the store's own units.

== Upgrade Notice ==

= 4.0.2 =
International exports now need an item description, HS tariff code and EDN.
Stores that have already saved their settings keep their values.
