Shippo shipping labels for GoCommerce

What it does

Configuration

Five things are required before it counts as set up: the API token, the carrier account, a default service level, and a ship-from street and country. Set them in Config from your own main(), or leave Config empty and 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. Pick an account and a serviceIn Shippo, note the object id of the carrier account to buy from and the service level token to use by default, and create an API token — live or test.
2. Install the moduleImport it and pass shippo.New to gocommerce.New, as below — or run the reference binary with -carriers, which installs every carrier module idle.
3. Fill in the settingsToken, carrier account, service level 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 an orderPOST /api/admin/create-fulfillment with the order id and the provider shippo. The engine records the tracking number and label URL and moves the order to shipped, or to partial.

import (
	"os"

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

app, err := gocommerce.New(cfg,
	shippo.New(shippo.Config{
		APIKey:            os.Getenv("SHIPPO_API_KEY"),
		CarrierAccount:    os.Getenv("SHIPPO_CARRIER_ACCOUNT"),
		ServicelevelToken: "usps_priority",
		From: shippo.Address{
			Name: "Acme", Street1: "215 Clayton St", City: "San Francisco",
			State: "CA", Zip: "94117", Country: "US", Phone: "+15553334444",
		},
	}),
)

How it works

• One synchronous purchase

  The label is bought with async set to false, so Shippo answers with the result rather than QUEUED. An asynchronous purchase would leave the engine holding a shipment with no tracking number — the half-booked state an operator cannot act on.

• A 200 is not a label

  Shippo can answer 200 or 201 with status ERROR and the reason in its messages. The module checks the status and the tracking number, so a refused purchase is an error the operator sees, never an order moved to shipped.

• The parcel the engine measured

  Weight comes from the variants when every line has one, otherwise from the default per unit. Sizes come from the engine only for a single unit of a single variant, else the configured box. Grams and millimetres go to Shippo unconverted, so nothing is rounded.

• Per-parcel overrides

  Meta on the ship request can name a different servicelevel_token or carrier_account for one parcel — which is where an operator who compared rates elsewhere passes the one they chose.

• Carrier read from the service

  The carrier code comes from the service level’s prefix — USPS, UPS, FedEx, DHL, Aramex, Canada Post, Australia Post — so the tracking number gets the right link. Anything else is left for the engine to work out from the number.

• Settings without a restart

  Before each shipment the panel’s values are laid over Config. With nothing in Config the module installs idle; with the required fields 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.

• No rate shoppingOne carrier account and one service level, from settings or meta. The module never asks Shippo for rates or picks the cheapest.
• No tracking updatesThe module keeps no state and registers no webhook. Scans and delivery events in Shippo do not reach the order; marking it delivered is still the operator’s job.
• No void callThere is no call to cancel a label. Deleting the fulfillment in GoCommerce does not touch the label or its postage in Shippo.
• One box per labelEach fulfillment buys one label for one parcel. A shipment in three boxes is three fulfillments.
• No customs declarationThe request carries no customs items, so a cross-border parcel that needs a declaration is not covered by the module as written.
• 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, and says so.