JavaScript SDK

v2.1.0

Lightweight JavaScript wrapper for the Shipthis API. Works in Node.js ≥18 and the browser. Ships TypeScript types.

GitHubApache-2.0Maintained

Installation

$ npm install shipthisapi-js

Browser — Injectable Script

html

<script src="https://cdn.jsdelivr.net/gh/shipthisco/shipthisapi-js@develop/dist/shipthisapi-js/main.js"></script>

Quick start

Initialize the client with your organisation ID and API key. Use your organisationId during development.

typescript

import { ShipthisAPI } from 'shipthisapi-js';

const shipthisApi = new ShipthisAPI({
  userType: 'employee',
  organisationId: 'your_org_id',
  xApiKey: SHIPTHIS_API_KEY,
  locationId: 'your_location_id',
  regionId: 'your_region_id',
});

await shipthisApi.connect();

// Fetch required reference data
const customers = await shipthisApi.Shipment.getCustomers();
const terms     = await shipthisApi.Shipment.getShipmentTerms();
const opExec    = await shipthisApi.Shipment.getOperationExecutive();

// Create a sea freight shipment
const shipment = await shipthisApi.Shipment.createSeaFreight({
  job_id: '',
  shipment_name: 'My first shipment',
  shipment_class: 'house',
  customer_name: customers.items[0],
  shipment_type: 'import',
  shipment_term: terms.items[0],
  operation_executive: opExec.items[0],
});

console.log('Shipment created:', shipment);

Resources & methods

Resource	Methods
`.sea_shipment`	create · retrieve · update · list
`.air_shipment`	create · retrieve · accept · list
`.invoice`	create · retrieve · update · list
`.customers`	create · retrieve · update · list
`.clearance_job`	create · retrieve · update · list

ℹ

The methods shown here are a sample of what the SDK covers. Shipthis exposes a generic collection API that gives access to every resource in the platform. See the full API reference ↗

Authentication

API key (recommended)

javascript

import { ShipthisAPI } from 'shipthisapi-js';

const shipthisApi = new ShipthisAPI({
  userType: 'employee',   // 'employee' | 'customer'
  organisationId: 'your_org_id',
  xApiKey: YOUR_API_KEY,
  locationId: 'your_location_id',
  regionId: 'your_region_id',
});

await shipthisApi.connect();

Password-based login

javascript

const shipthisApi = new ShipthisAPI({
  userType: 'employee',
  organisationId: 'your_org_id',
  locationId: 'your_location_id',
  regionId: 'your_region_id',
});

await shipthisApi.loginViaPassword('user@example.com', 'your_password');

Shipment operations

Shipments are grouped by mode — air, sea, or land. Each mode exposes the same create / get / getAll / update shape.

javascript

// Fetch reference data first
const customers   = await shipthisApi.Shipment.getCustomers();
const terms       = await shipthisApi.Shipment.getShipmentTerms();
const opExec      = await shipthisApi.Shipment.getOperationExecutive();

// Create a sea freight shipment
const shipment = await shipthisApi.Shipment.createSeaFreight({
  job_id: '',
  shipment_name: 'Demo sea shipment',
  shipment_class: 'house',
  customer_name: customers.items[0],
  shipment_type: 'import',
  shipment_term: terms.items[0],
  operation_executive: opExec.items[0],
});

console.log('Created:', shipment);

Load creation

Loads attach to an existing shipment job.

javascript

await shipthisApi.Shipment.createSeaFclLoad(payload);
await shipthisApi.Shipment.createAirLoad(payload);
await shipthisApi.Shipment.createLandFtlLoad(payload);

Customer management

javascript

// Register a new customer portal user
await shipthisApi.customerUserRegistration(
  'john.doe@example.com',
  'StrongPassword123!',
  'John',
  'Doe',
  "John's Logistics",
  true  // terms accepted
);

// Create a customer record
const customer = await shipthisApi.Shipment.createCustomer(customerData);

// Add shipper / consignee party to a customer
await shipthisApi.Shipment.createCustomerParty(partyData, customer.id);

Reference data lookups

javascript

const ports       = await shipthisApi.Shipment.getAirPort();
const containers  = await shipthisApi.Shipment.getContainerType();
const currencies  = await shipthisApi.Shipment.getCurrency();
const shippers    = await shipthisApi.Shipment.getShipper();
const consignees  = await shipthisApi.Shipment.getConsignee();
const lines       = await shipthisApi.Shipment.getShippingLineName();
const vehicles    = await shipthisApi.Shipment.getVehicleType();
const packages    = await shipthisApi.Shipment.getPackageTypeList();

Setup module

javascript

const productTypes = await shipthisApi.Setup.getProductType();
const allPorts     = await shipthisApi.Setup.getPort();
const awbBlocks    = await shipthisApi.Setup.getAWBBlock();
const airports     = await shipthisApi.Setup.getAllAirport();

All SDKs Resources