NimbusPost shipping for GoCommerce

What it does

Configuration

Three settings are required: the account’s email and password, and the warehouse name. 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. Register the warehouseIn NimbusPost, register the pickup warehouse and note its name exactly, along with the account login the module will use.
2. Install the moduleImport it and pass nimbuspost.New to gocommerce.New, as below — or run the reference binary with -carriers, which installs every carrier module idle.
3. Configure itEmail, password and warehouse name, in Config or under Settings › Shipping providers. Decide whether booking should also raise the pickup.
4. Ship an orderChoose NimbusPost in the admin’s ship dialog, or POST /api/admin/create-fulfillment with "provider": "nimbuspost". The courier’s waybill becomes the tracking number.

import (
	"os"

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

app, err := gocommerce.New(cfg,
	nimbuspost.New(nimbuspost.Config{
		Email:         os.Getenv("NIMBUSPOST_EMAIL"),
		Password:      os.Getenv("NIMBUSPOST_PASSWORD"),
		WarehouseName: "Primary",
	}),
)

How it works

• One booking call

  The parcel goes to NimbusPost’s shipments endpoint with the consignee, the pickup, this parcel’s items, weight and size. The answer carries the waybill, the courier’s name and a label URL.

• status: false is a refusal

  NimbusPost can answer HTTP 200 with "status": false. Every response is checked for the flag before anything is believed, so a refusal never reads as a shipped order.

• The courier, not the aggregator

  The courier’s name is mapped to one of the engine’s carrier codes — Delhivery, XpressBees, Blue Dart, Ecom Express, DTDC, Shadowfax, Ekart, Amazon Shipping, India Post, DHL, FedEx — so the number gets the right tracking link.

• COD or prepaid, from the order

  An unpaid order is booked cod and a paid one prepaid, with the order amount set to the value of what is in this parcel.

• Measured weight first

  Weight in grams, sides in centimetres. The engine’s summed weight is used only when every line was weighed; otherwise the default per unit. A courier_id in the request’s meta asks for that courier.

• A token a day, an id per parcel

  The login’s token is reused for 24 hours and cleared on a 401. NimbusPost rejects a duplicate order number, so later parcels on one order go as number-2, number-3.

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.

• A booking without a waybillIf NimbusPost creates the shipment but assigns no waybill, the call fails with the code’s own instruction: cancel it in NimbusPost before retrying.
• No tracking updatesNothing comes back after booking: no webhook, no polling. Marking an order delivered is a separate step, in the admin or through the API.
• No rates, no cancellationThe module quotes no rates, and deleting a fulfillment in GoCommerce does not cancel the shipment in NimbusPost.
• Courier choice needs the APIThe admin’s ship dialog sends no meta, so asking for a particular courier_id is an API call.
• A password, not a keyNimbusPost’s API has no long-lived key, so the module has to hold the account’s email and password to log in with.
• Two-decimal moneyPrices and the order amount are minor units divided by 100 — right for rupees, wrong for a currency with none or three decimals.