Simple Commerce Australia Post Laravel Package

Getting Started

This package wires Australia Post shipping rates into Simple Commerce. Start by reading the package README and config/australia-post.php (published via php artisan vendor:publish --tag="australia-post-config") — it holds your Australia Post API key, account number, and default parcel/from-address details.

Minimal steps:

1. composer require mitydigital/simple-commerce-australia-post
2. Publish the config and add credentials to .env (never commit the API key).
3. Register the shipping method in config/simple-commerce.php under shipping.methods.
4. Create a test cart, hit the checkout shipping step, and confirm live rates return.

First use case: offering calculated Parcel Post / Express Post rates at checkout based on cart weight and destination postcode.

3.0.2 note: this patch ("Correct product reference") fixes how the Australia Post product is referenced when building rate requests. If you were on 3.0.1 and saw empty or wrong rate responses, upgrade — but it's a patch, so no config or API changes are required.

Implementation Patterns

• Config-driven shipping method. Treat the package as a Simple Commerce shipping provider: the class is registered once and Simple Commerce calls it during the shipping-rate step. Keep all credentials and defaults in config, not in the provider class.
• Multiple services, one provider. Wrap each service (Parcel Post, Express Post, international where supported) as a distinct config entry / method so customers can pick speed at checkout rather than hardcoding one.
• Cart-to-parcel mapping. Centralise the logic that converts cart line items into Australia Post parcel dimensions/weights (a small service or trait). This is the bit you'll tune most — weights, cubic dimensions, packaging rules.
• Cache rate lookups. Cache responses keyed on (destination postcode, weight, service) for a short TTL to avoid hammering the API on every cart update and to stay within rate limits.
• Free shipping / thresholds. Handle "free over $X" before calling the provider — don't rely on Australia Post to return a zero rate.
• Testing. Fake the HTTP layer (Http::fake()) in feature tests with recorded Australia Post responses so checkout tests don't depend on the network or credentials.

Gotchas and Tips

• Address data quality. Australia Post rating is only as good as the destination postcode/suburb; validate the postcode before requesting rates or you'll get empty responses that look like package failures.
• Product reference (fixed in 3.0.2). If rates were silently empty on 3.0.1, verify the upgrade resolved it before debugging config — this was the exact bug patched.
• Weight units. Confirm the units the package expects (grams vs kg) match what you feed it; a 1000× error is the classic cause of absurdly high rates.
• Sandbox vs live. Check whether the config exposes a test/sandbox endpoint; credentials for live and test are separate.
• Timeouts and failures. Wrap calls defensively and decide on a fallback (flat rate or "shipping calculated at next step") so a slow API doesn't break checkout.
• Logging. Log the outgoing payload and response at debug level while integrating — Australia Post error messages are terse and hard to map back to your cart otherwise.
• Extension points. Keep your parcel-mapping and caching in your own classes rather than forking the package; the provider is thin, and re-implementing its request building locally is usually less painful than patching it.
• Version pinning. Given the 3.0.1 → 3.0.2 fix landed inside the 3.x line, pin minor versions (~3.0.2) and read the changelog on each patch — patch releases here have contained behaviour fixes, not just docs.