ShipStation labels for GoCommerce

What it does

Configuration

Four things are required: the API key, a default service code, and a ship-from address line 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. Get a V2 API keyIn ShipStation, create a key for the V2 API and note the service code to buy by default. A key and secret for the older ssapi will not work here.
2. Install the moduleImport it and pass shipstation.New to gocommerce.New, as below — or run the reference binary with -carriers, which installs every carrier module idle.
3. Fill in the settingsKey, service code 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 shipstation. 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"
	shipstation "github.com/itswadesh/gocommerce/ext/fulfill-shipstation"
)

app, err := gocommerce.New(cfg,
	shipstation.New(shipstation.Config{
		APIKey:      os.Getenv("SHIPSTATION_API_KEY"),
		ServiceCode: "usps_priority_mail",
		From: shipstation.Address{
			Name: "Acme", AddressLine1: "215 Clayton St",
			CityLocality: "San Francisco", StateProvince: "CA",
			PostalCode: "94117", CountryCode: "US", Phone: "+15553334444",
		},
	}),
)

How it works

• A label from a described parcel

  POST /v2/labels carries the service code, the ship-from and ship-to addresses and one package. The answer is a tracking number and a label download; the module keeps the PDF link, or the generic link, or the PNG.

• No tracking number, no shipment

  A label that comes back without a tracking number is an error, not a shipment, so the order is never moved to shipped on a parcel nobody can trace.

• Centimetres, keeping the tenth

  ShipStation takes grams, which the engine stores, and centimetres, which it does not. Sides are divided by ten and sent as decimals — 305 mm is 30.5 cm, not 30 — because, as the package puts it, rounding down is how a parcel gets refused at the counter for being over its band.

• A unique id per parcel

  Each label carries external_shipment_id: the order number on a first shipment, with -2, -3 appended for later parcels against the same order, so ShipStation never sees a repeat.

• Per-parcel overrides

  Meta on the ship request can name a different service_code, or a carrier_id, for one parcel.

• Carrier worked out

  The carrier code comes from what ShipStation reports, or from the service code — USPS (Stamps.com and Endicia labels too, since USPS carries them), FedEx, UPS, DHL, Canada Post, Australia Post — so the tracking number gets the right link.

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 shoppingThe service is a setting or a meta override. The module never asks ShipStation for rates or picks one for you.
• No tracking updatesNo webhook and no stored state: delivery events in ShipStation 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 in ShipStation.
• V2 keys onlyCredentials for the older ssapi — a key and a secret over HTTP Basic — do not work; the module speaks only the V2 API.
• 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.