README
¶
shiprocket-go
Go SDK for the Shiprocket External API (v1).
Requirements
- Go 1.21+
go get github.com/timslabs/shiprocket-go
Authentication
Create an API user in the Shiprocket panel: Settings → API → Configure → Create an API User (not your panel login).
Authenticate with email and password to receive a JWT (valid for 10 days / 240 hours). The SDK attaches it as Authorization: Bearer {token} on subsequent requests.
import (
shiprocket "github.com/timslabs/shiprocket-go"
)
client := shiprocket.NewClient(
os.Getenv("SHIPROCKET_EMAIL"),
os.Getenv("SHIPROCKET_PASSWORD"),
)
// JWT is fetched automatically on the first authenticated call.
// Or authenticate explicitly:
if err := client.Authenticate(); err != nil {
log.Fatal(err)
}
Or manage the token yourself:
client := shiprocket.NewClientWithToken(os.Getenv("SHIPROCKET_TOKEN"))
Quick start
package main
import (
"fmt"
"log"
"os"
shiprocket "github.com/timslabs/shiprocket-go"
)
func main() {
client := shiprocket.NewClient(
os.Getenv("SHIPROCKET_EMAIL"),
os.Getenv("SHIPROCKET_PASSWORD"),
)
rates, err := client.Courier.Serviceability(map[string]interface{}{
"pickup_postcode": "110030",
"delivery_postcode": "122001",
"weight": 0.5,
"cod": 0,
}, nil)
if err != nil {
log.Fatal(err)
}
fmt.Printf("%v\n", rates)
order, err := client.Order.CreateAdhoc(map[string]interface{}{
"order_id": "ORD-1001",
"order_date": "2026-08-13",
"pickup_location": "Primary",
"billing_customer_name": "Jane",
"billing_last_name": "Doe",
"billing_address": "221B Baker Street",
"billing_city": "Mumbai",
"billing_pincode": "400001",
"billing_state": "Maharashtra",
"billing_country": "India",
"billing_email": "jane@example.com",
"billing_phone": "9999999999",
"shipping_is_billing": true,
"payment_method": "Prepaid",
"sub_total": 499,
"length": 10,
"breadth": 10,
"height": 10,
"weight": 0.5,
"order_items": []map[string]interface{}{
{
"name": "Widget",
"sku": "W-1",
"units": 1,
"selling_price": 499,
},
},
}, nil)
if err != nil {
log.Fatal(err)
}
awb, err := client.Courier.AssignAwb(map[string]interface{}{
"shipment_id": order["shipment_id"],
}, nil)
if err != nil {
log.Fatal(err)
}
_, err = client.Courier.GeneratePickup(map[string]interface{}{
"shipment_id": []interface{}{order["shipment_id"]},
}, nil)
if err != nil {
log.Fatal(err)
}
fmt.Printf("AWB response: %v\n", awb)
}
Successful responses are map[string]interface{} (decoded JSON). Failed HTTP responses return typed errors from the errors package (BadRequestError, ServerError, AuthError).
All resource methods accept an optional extraHeaders map[string]string as the last argument.
Configuration
client := shiprocket.NewClient(email, password)
client.SetTimeout(60) // seconds
client.SetUserAgent("MyApp/1.0")
client.AddHeaders(map[string]string{
"X-Custom": "value",
})
client.SetBaseURL("https://apiv2.shiprocket.in") // default
Base URL: https://apiv2.shiprocket.in
External API prefix: /v1/external
API groups
| Resource | Coverage |
|---|---|
Auth |
Login, logout |
Order |
Create / update / cancel / address / fulfill / mapping / import / export / invoice / returns |
Courier |
Serviceability, courier list, AWB, pickup, label, manifest, track (AWB / shipment / order / bulk) |
Shipment |
List / show / create forward & return |
Pickup |
List / add pickup locations |
Product |
Catalogue + bulk import / sample |
Inventory |
List / update |
Listing |
Channel catalog mappings (list / link / import / export) |
Channel |
Channels, countries, zones, postcode details |
Account |
Wallet balance, statement, billing discrepancy |
Ndr |
NDR list / details / action |
Import |
Bulk import error / status check |
International |
International orders, couriers, manifest, KYC, bank details |
Warehouse |
Warehouse SRF serviceability (/v1/warehouse, not under /v1/external) |
Package layout
shiprocket-go/
client.go # NewClient, resource wiring
version.go
constants/ # URLs, headers, status codes
errors/ # BadRequestError, ServerError, AuthError
requests/ # HTTP Get/Post/Put/Patch/Delete/File
resources/ # API resource methods
documents/ # Per-resource usage examples
testdata/ # JSON fixtures for tests
utils/ # Test helpers
Tests
go test ./...
go test ./... -v
go test ./resources -run TestAccountWalletBalance -v
Related
- Shiprocket API docs
- PHP SDK:
tims/shiprocket-php-sdk - Laravel package:
tims/laravel-shiprocket
License
MIT
Documentation
¶
Index ¶
Constants ¶
const SDKName = "shiprocket-go"
SDKName is the name of this SDK.
const SDKVersion = "1.0.1"
SDKVersion is the current package version.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
*requests.Request
Auth *resources.Auth
Order *resources.Order
Courier *resources.Courier
Shipment *resources.Shipment
Pickup *resources.Pickup
Product *resources.Product
Inventory *resources.Inventory
Listing *resources.Listing
Channel *resources.Channel
Account *resources.Account
Ndr *resources.Ndr
Import *resources.Import
International *resources.International
Warehouse *resources.Warehouse
}
Client provides helper methods to call Shiprocket's External APIs.
func NewClient ¶
NewClient creates a Shiprocket client using API user email/password. The JWT is obtained lazily on the first authenticated request (or via Authenticate).
func NewClientWithToken ¶
NewClientWithToken creates a client that uses an existing JWT bearer token.
func (*Client) AddHeaders ¶
AddHeaders adds additional headers to all subsequent requests.
func (*Client) Authenticate ¶
Authenticate obtains a JWT using the credentials passed to NewClient.
func (*Client) SetBaseURL ¶
SetBaseURL overrides the API host (useful in tests).
func (*Client) SetTimeout ¶
SetTimeout sets the HTTP timeout in seconds.
func (*Client) SetUserAgent ¶
SetUserAgent sets a custom User-Agent prefix.
Source Files
Directories