Easyship shipping for GoCommerce

What it does

Configuration

Four things are required: the access token, a default courier service, 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 token and a courierIn Easyship, create an access token with the public.shipment:write and public.label:write scopes, and note the id of the courier service to book by default.
2. Install the moduleImport it and pass easyship.New to gocommerce.New, as below — or run the reference binary with -carriers, which installs every carrier module idle.
3. Fill in the settingsToken, courier service and ship-from address in Config or under Settings › Shipping providers — and tick the pounds-and-inches box if that is what your Easyship account reads.
4. Ship an orderPOST /api/admin/create-fulfillment with the order id and the provider easyship. 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"
	easyship "github.com/itswadesh/gocommerce/ext/fulfill-easyship"
)

app, err := gocommerce.New(cfg,
	easyship.New(easyship.Config{
		Token:            os.Getenv("EASYSHIP_TOKEN"),
		CourierServiceID: os.Getenv("EASYSHIP_COURIER_SERVICE_ID"),
		From: easyship.Address{
			ContactName: "Acme", Line1: "Kennedy Town", City: "Hong Kong",
			PostalCode: "0000", CountryAlpha2: "HK",
			ContactPhone: "+852-3008-5678", ContactEmail: "ship@acme.test",
		},
	}),
)

How it works

• One call, with the label

  The shipment, the courier service and buy_label go to Easyship together. A shipment that comes back with no tracking number is an error that names the Easyship shipment id and says to cancel it in Easyship before retrying.

• Customs from what is in the box

  Each line in this parcel goes as a customs item — title, SKU, quantity, and the unit price as declared value in the line’s currency. The weight is sent once, for the whole parcel, because the engine knows it per parcel, not per line.

• The units the account reads

  Metric by default: grams to kilograms, millimetres to centimetres. With Imperial set, pounds and inches instead. Conversions round half up, the direction that over-declares rather than under-declares a parcel.

• The label, not the paperwork

  Of the documents Easyship issues, the module stores the one in the label category as the shipment’s label URL. Commercial invoices and packing slips stay in Easyship.

• The order, named

  The order number and its creation time go to Easyship as order_data, under the platform name gocommerce, so the shipment can be found from the store’s own number.

• Carrier worked out

  The carrier code is read from the courier Easyship reports — USPS, FedEx, UPS, DHL, Aramex, Delhivery, Royal Mail — so the tracking number gets the right link. Anything else is left for the engine to work out from the number.

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 courier service, from settings or meta. The module never asks Easyship for rates or picks the cheapest.
• No tracking updatesNo webhook and no stored state: delivery events in Easyship do not reach the order. Marking it delivered is still the operator’s job.
• No cancel callA half-booked shipment has to be cancelled in Easyship by hand, and deleting the fulfillment in GoCommerce does not touch it.
• Customs values assume two decimalsThe declared value is the unit price in minor units divided by 100. For a currency with no minor unit, such as the yen, that declares a hundredth of the price.
• Thin customs itemsItems carry title, SKU, quantity and value only — no HS code and no country of origin, although the package comment lists origin country among them.
• 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.