Postage for WordPress — installation guide

Postage for WordPress

Adds live shipping rates — and optionally real label sales — to any WordPress site, with no WooCommerce required. It gives you two shortcodes:

• [postage_rate_calculator] — a quote-only calculator. A visitor types a destination and weight and sees live rates. It never spends anything, so it's safe on any public page.
• [postage_buy_label] — quotes a rate and buys it, spending your Postage account balance.

Running a WooCommerce store? Use Postage for WooCommerce instead — it does the same things backed by a real cart, checkout and payment step. The two can be installed side by side.

Requirements

• 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)

Download Postage for WordPress →

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. WordPress site.
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

The easy way — upload the zip

1. Download the plugin zip.
2. In WordPress, go to Plugins → Add New → Upload Plugin.
3. Choose the zip, click Install Now, then Activate Plugin.

The manual way — SFTP

1. Unzip it, then upload the whole postage-wordpress folder into wp-content/plugins/ so you end up with wp-content/plugins/postage-wordpress/postage-wordpress.php.
2. Go to Plugins and click Activate under Postage for WordPress.

Don't rename the folder — WordPress identifies the plugin by its path.

If WordPress refuses to activate it and mentions a PHP or WordPress version, your host is below the minimums above. Ask your host to move you to PHP 8.0+; nothing in the plugin can work around it.

Step 3 — Connect it to your account

Activating adds a Postage item to the wp-admin sidebar (look for the ✈ icon, near the bottom). Open it — the screen is titled Postage Settings. You need the manage_options capability, i.e. an Administrator.

Connection

Ship-from address

Every one of the eight fields is marked required by the form, including Address line 2 and Phone — your browser won't let you save until all eight have something in them. Put a single character in ones that don't apply.

Country must be the 2-letter code (US, GB). This one matters more than it looks: if it's blank or wrong, every quote is treated as international and gets customs data attached, which distorts your rates.

Default package dimensions

Length, width and height in inches, used for every quote and purchase — there is no per-shipment size input anywhere on the front end. Weight is always typed by the visitor on the form, in ounces.

Click Save Changes. Nothing renders on the front end until both the site URL and the token are filled in.

Step 4 — Put it on a page

Create or edit a page and add the shortcode. In the block editor, add a Shortcode block and type it in; in the classic editor just type it into the content.

Rate calculator — safe anywhere

[postage_rate_calculator]

Renders a form (destination + weight in oz) and a Get rates button that lists live rates. It never spends anything.

Buy a label — spends your balance

[postage_buy_label]

The same form plus recipient name and phone. Picking a rate buys the label immediately from your account balance, then offers a download link.

Neither shortcode takes any attributes — anything you add is ignored.

Put each shortcode on its own page. The two forms use the same internal element IDs, so if both are on one page the scripts collide and the buy form drives the calculator's results. The same applies to using either shortcode twice on one page.

Who is allowed to buy a label

This is the setting to think hardest about, because plain WordPress has no cart, checkout or payment step. When a visitor buys a label here, your Postage balance is debited and nothing is collected from them. The plugin can't take their money — only you can arrange that.

Under Features → Who can buy a label:

• Logged-in users only (recommended) — the default. Guests see the form with a "Please log in to buy a shipping label" notice and the rate buttons disabled. This is enforced on the server too, so it can't be bypassed by editing the page.
• Anyone (including anonymous visitors) — any visitor who can reach the page can spend your balance. Only choose this if you're restricting access another way (a membership plugin, a secret URL, a staff-only network).

The quote-only calculator is never gated — anyone who can load the page can pull quotes. Quotes cost nothing.

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.

The Name / company ship-from field falls back to your site title if you leave it blank. The other seven have no fallback.

Known limitations

Worth knowing before you file a bug — these are real behaviours of version 1.0.0:

• The "Test mode" checkbox does nothing. Sandbox versus live is decided entirely by which token you paste. To stop spending real money, paste a Test token. Ticking this box is not a safety switch.
• The three checkboxes can't be switched off. "Test mode", "Rate calculator" and "Shipping Label purchase" re-enable themselves whenever you save the settings form. To take a feature off a page, remove its shortcode.
• The blocks don't appear in the block inserter. Use a Shortcode block. (The readme mentions blocks; they're registered server-side only, so there's no inserter entry.)
• The label link is shown once — but it never expires. The download link appears only in the moment after purchase, and WordPress keeps no record of the order. It is a secret capability link: anyone holding it can download that label, repeatedly, without logging in, so treat it like a password and don't paste it anywhere public. The only thing that revokes it is rotating the salts in wp-config.php, which invalidates every outstanding label link at once. If the buyer loses the tab, get the label from your Postage account.
• Labels download as .png regardless of the underlying format.
• The plugin waits about 60 seconds for a label after purchase. If it isn't ready, it stops polling and tells the buyer to check back — the label still appears in your Postage account.
• Uninstalling leaves your settings behind, API token included, in the wp_options table. Clear the fields before deleting the plugin if that matters to you.

Troubleshooting

Still stuck? Send us the exact message and we'll take a look.