USPS labels for GoCommerce

What it does

Configuration

Eight settings are required: the developer application’s client id and secret, the CRID, MID and payment account from the Business Customer Gateway, a default mail class, and a ship-from street address and ZIP code. Set them in Config, or fill them in under Settings › Shipping providers.

The module reads its Config struct, not the environment. The variable names are the ones the package’s own example or the reference binary uses; in your own main() you choose where each value comes from. Where a setting has a panel label, the admin’s settings drawer can hold it too, and a value typed there wins over Config.

Setting it up

1. Get the credentialsA USPS developer application gives the client id and secret; the Business Customer Gateway gives the CRID, the MID and the Enterprise Payment System account that pays for postage.
2. Install the moduleImport it and pass usps.New to gocommerce.New, as below — or run the reference binary with -carriers, which installs every carrier module idle.
3. Fill in the settingsCredentials, mail class and ship-from address, in Config or under Settings › Shipping providers. A value typed into the panel counts on the next shipment, with no restart.
4. Ship and printPOST /api/admin/create-fulfillment with the order id and the provider usps. The shipment’s label URL points at /api/admin/x/fulfill-usps/labels/{tracking}, which serves the PDF.

import (
	"os"

	"github.com/itswadesh/gocommerce/core"
	usps "github.com/itswadesh/gocommerce/ext/fulfill-usps"
)

app, err := gocommerce.New(cfg,
	usps.New(usps.Config{
		ClientID:      os.Getenv("USPS_CLIENT_ID"),
		ClientSecret:  os.Getenv("USPS_CLIENT_SECRET"),
		CRID:          os.Getenv("USPS_CRID"),
		MID:           os.Getenv("USPS_MID"),
		AccountNumber: os.Getenv("USPS_EPS_ACCOUNT"),
		From: usps.Address{
			FirstName: "Acme", StreetAddress: "4120 Bingham Ave",
			City: "St. Louis", State: "MO", ZIPCode: "63116",
		},
	}),
)

How it works

• Two tokens, cached

  The bearer token is kept until a minute before it expires; the payment authorisation for four hours, half the eight USPS gives it. A 401 drops both, so the next attempt mints a fresh pair rather than retrying a dead one.

• The label, stored and served

  The base64 PDF is decoded and kept in the module’s own table, keyed by tracking number, and served inline for printing to an operator who can read orders — nobody else.

• Postage is never lost to a missing PDF

  If the label image cannot be decoded or stored, the shipment still stands with its tracking number and the failure is logged. Refusing it would leave postage paid for and an order the engine says is unshipped.

• Rounded up, not down

  Weight goes to USPS in pounds and sides in inches, both rounded up to the hundredth. A parcel declared lighter than it is comes back with postage due; one a hundredth heavier costs a cent.

• ZIP+4 split

  A ZIP+4 typed as one string — 94117-1234, or nine digits — is split into the two fields USPS takes, because it rejects the joined form in ZIPCode.

• Settings without a restart

  Before each shipment the panel’s values are laid over Config. With nothing in Config the module installs idle; with every required field in Config it starts switched on.

What it does not do

Read these before an order depends on it. No store is known to run GoCommerce in production yet, so these come from the code, not from anyone’s experience.

• Domestic addresses onlyThe label request carries no country and no customs form, so as written it is for parcels within the United States.
• 4×6 PDF labels onlyThe image type and size are fixed in the code; there is no setting for ZPL or another size.
• An EPS account is neededLabel creation is paid through the payment authorisation, so a store without a CRID, MID and payment account from the Business Customer Gateway cannot buy a label with this module.
• No tracking updatesNo webhook: scans and delivery events at USPS do not reach the order. Marking it delivered is still the operator’s job.
• No cancel callThere is no call to cancel a label. Deleting the fulfillment in GoCommerce does not touch the label or its postage at USPS.
• A guessed box for several itemsFor anything but a single unit, the size sent is the configured default, not a measurement. The engine does not pack cartons.