Postage for WooCommerce — installation guide

Postage for WooCommerce

Connects your WooCommerce store to your Postage account. Three capabilities, each independent — turn on only what you need:

1. Live rates at checkout — a Postage shipping method quotes real rates for the shopper's cart and offers each as a delivery option.
2. Buy the real label — for an existing order, buy its label with a click, or automatically when the order reaches a status you choose. Tracking and a downloadable label land on the order.
3. Shipping Label product — sell a label as a product: the shopper gets a live quote form instead of a fixed price, and the exact label they choose is bought once they pay.

No WooCommerce? Use Postage for WordPress instead.

Requirements

• WooCommerce 8.0 or newer, WordPress 6.0 or newer
• PHP 8.0 or newer — WordPress refuses to activate the plugin on anything older
• A Postage account with an API token (see step 1)

Compatible with WooCommerce High-Performance Order Storage (HPOS).

Download Postage for WooCommerce →

Step 1 — Create your API token

The plugin signs every request with a personal access token. Create one before you install, so you can paste it straight in.

1. Log in to your Postage account and open Account → API tokens.
2. Click Create token and give it a name you'll recognise later, e.g. WooCommerce store.
3. Grant exactly these four abilities — the plugin uses all of them and nothing more:
   • rates:read — quote live rates
   • carts:write — build the cart behind a purchase
   • orders:read — read back tracking numbers and labels
   • orders:write — place the order that buys the label (spends your balance)
4. Choose the mode:
   • Test — recommended for setup. Nothing is charged, no real label is bought; you get a TEST… tracking code and a sample label.
   • Live — buys real labels and debits your account balance.
5. Copy the token now. It is shown once — if you lose it, delete it and create another.

Keep your balance topped up. A label is paid from your Postage account balance at the moment it's bought. If the balance is too low the purchase fails with an "Insufficient account balance" error, and (for WooCommerce) the failure is written to the order's notes.

Step 2 — Install & activate

Install WooCommerce first. Without it active, this plugin does nothing except show "Postage for WooCommerce requires WooCommerce to be installed and active."

1. Download the plugin zip.
2. Plugins → Add New → Upload Plugin, choose the zip, Install Now, then Activate Plugin.

Prefer SFTP? Upload the postage-woocommerce folder to wp-content/plugins/ and activate from the Plugins screen. Don't rename the folder.

Step 3 — Connect it to your account

Activating adds a Postage item to the sidebar (✈ icon). Open it — Postage Settings. You need the manage_woocommerce capability (Administrator or Shop Manager).

Connection

Features

Ship-from address

Leave every field blank to use your WooCommerce store address (WooCommerce → Settings → General) — usually what you want. To override, you must fill in at least Address line 1; that's the switch that turns the whole override on. Country is the 2-letter code.

Default package

Used when a product has no weight or dimensions of its own — default 16 oz in a 10×8×4 in box. Set your store's weight and dimension units in WooCommerce → Settings → Products; the plugin converts automatically.

Click Save Changes.

Step 4 — Turn on live rates at checkout

Enabling the feature is only half of it — WooCommerce won't quote until the method is in a shipping zone. This is the single most common reason rates don't show up.

1. Go to WooCommerce → Settings → Shipping.
2. Pick the zone you want to quote for (or Add zone and set its regions).
3. Click Add shipping method, choose Postage, and add it.
4. Click into it to set:
   • Title — what the shopper sees as the delivery option group. Default: Postage.
   • Markup % — an optional percentage added on top of the retail rate. Leave 0 to pass the rate through at cost. Charge 10 to add 10% to every quote.
5. Save, then test: add a product to the cart and go to checkout. Each live rate appears as its own delivery option, labelled like USPS Priority (2 days).

Rates are cached for 5 minutes per cart and customer, so an address edit may briefly show the previous quote.

If no rates appear at checkout, the plugin stays silent by design — a shopper never sees an error. Check: the method is in a zone that matches the address, the token is valid, and your ship-from address is complete. Turn on WP_DEBUG and check WooCommerce → Status → Logs (source postage-woocommerce) for the real reason.

Step 5 — Buy labels for orders

Open any order. The Postage box sits in the sidebar.

• Buy Postage label — buys the label now, from your account balance. Appears until a label has been bought.
• Check status — buying is asynchronous; this re-checks and pulls in the tracking number and label.
• Download label — appears once the label is ready.

The order's notes record each step, including failures with the reason.

The plugin buys one parcel per order — no bin-packing. It uses the product's own dimensions only when the order is a single item at quantity 1 with dimensions set; otherwise it falls back to your default box.

Put a weight on every product you ship. Order weight is the sum of the line weights, and your default weight is used only when the entire order weighs nothing. A weightless product sitting alongside weighed ones contributes zero rather than falling back — so the parcel is under-weighed and the rate comes back too cheap.

Buying automatically

Set Label purchase to Auto and pick a status (usually Processing). Every order entering that status buys its label with no clicks. Start with Manual until you've seen a few orders go through correctly.

If the shopper picked a Postage rate at checkout, the plugin buys that carrier and service. If it's no longer available, it falls back to the cheapest rate quoted — so the service bought may differ from what they chose. Check the order notes.

Step 6 — Webhooks (recommended)

Buying a label is asynchronous on our side. Without webhooks you must press Check status; with them, tracking numbers and labels land on the order by themselves. Set this up — it's five minutes.

1. On Postage Settings, copy the Webhook URL shown on the screen. It looks like https://your-store.com/wp-json/postage/v1/webhook. Copy the exact value rendered there — if your permalinks are set to Plain, it'll be the ?rest_route= form instead, and that's the one that works.
2. In your Postage account, go to Account → Webhooks and add that URL.
3. Subscribe it to order.completed and tracking.updated.
4. Copy the endpoint's signing secret (starts with whsec_) and paste it into Webhook signing secret on the settings screen. Save.

Every delivery is verified with an HMAC-SHA256 signature in the X-Postage-Signature header, so an attacker can't forge a status update.

Check it works

Buy a label on a test order. Within a few seconds the tracking number should appear without you pressing anything. If not, check the delivery log on the Webhooks page:

Selling a label as a product

For when the label is what you're selling, rather than shipping for goods.

1. Create a Simple product.
2. In Product data → General, tick Postage Shipping Label.
3. Publish. The price and Add-to-cart are replaced by a live quote form (destination + weight); the shopper picks a rate and it's added to the cart at that price.
4. When the order is paid, the exact label they chose is bought automatically. They download it from the order confirmation and My account → Orders.

Intended for simple products — that's where the checkbox appears. The purchase fires on payment completion, so gateways that don't report payment (some manual, cash-on-delivery or free-order flows) won't trigger it.

These items don't get status updates from webhooks, and have no "Check status" button. If the label isn't ready the moment payment completes, the customer sees "Being prepared — check back soon" until they reload later. It'll be waiting in your Postage account either way.

Units & the ship-from address

• Weight is in ounces (oz) and dimensions are in inches (in) on the settings screen and the quote forms.
• Country must be the 2-letter code — US, GB, DE. Not "United States".
• Prices come back from Postage in USD and are displayed with a $. There is no currency conversion.
• When the ship-from and ship-to countries differ, the shipment is quoted as international and customs details are attached automatically.

Your store's own weight and dimension units (WooCommerce → Settings → Products) are converted for you, so set them to whatever you already use.

Known limitations

Real behaviours of version 1.0.0, worth knowing up front:

• The "Test mode" checkbox does nothing. Sandbox versus live depends only on which token you paste. Use a Test token while setting up.
• The three checkboxes can't be switched off. "Test mode", "Live rates at checkout" and "Shipping Label product" re-enable themselves on save. To stop quoting at checkout, remove the Postage method from the shipping zone. To stop selling label products, untick the box on the product.
• Labels download as .png regardless of the underlying format.
• Checkout rate failures are silent — deliberately, so shoppers never see an error. Use the logs.
• Shipping Label product items ignore webhooks and have no status button (see above).
• One parcel per order — no bin-packing or multi-box splitting.
• Checkout quotes use your store name as the recipient, since the shopper's name isn't known before checkout. It doesn't affect the price.

Troubleshooting

Still stuck? Send us the order number and the exact message.