API - Shipment

Created by KloudShip Support, Modified on Fri, 24 Oct at 7:43 PM by KloudShip Support

GET: Shipments

The GET Shipments API endpoint is used for retrieving all shipment list information. The response provides comprehensive details about the shipments, including addresses, packages, rates, labels, and more. Use the provided request example and response format to integrate this API into your application for seamless shipment tracking and management.

Endpoint details:

Method	POST
Production Environment URL	https://api.kloudship.com/api/v1/Shipment
Test Environment URL	https://api-ppd.kloudship.com:960/api/v1/Shipment
Content-Type	application/json

Query paramters:

Parameter	Type	Description
`pageNumber`	`integer`	The current page number to retrieve.
`newestFirst`	`boolean`	Sort shipments by most recent first (`true`) or oldest first (`false`).
`searchString`	`string`	Keyword or term to search shipments (e.g., tracking number or order ID).
`processedStatuses`	`string`	Filter by processed shipment status (e.g., `PreTransit`, `Intransit`).
`carriers`	`string`	Filter shipments by carrier name (e.g., `Delhivery`, `XpressBees`).
`orderTypes`	`string`	Filter by order type (e.g., `Prepaid`, `Cod`).
`statuses`	`string`	Filter by general status (e.g., `Confirmed`, `Pending, Failed`).
`carrierAccountIds`	`string`	Filter by specific carrier account IDs.
`additionalFilter`	`string`	Optional field for environment-specific filtering.
`accountIds`	`string`	Filter shipments by account identifiers.
`fromDate`	`string`	Start date for filtering (ISO 8601 format).
`toDate`	`string`	End date for filtering (ISO 8601 format).

Request body:

Does not require any request parameter

Example cURL:

curl --location 'https://api-ppd.kloudship.com:960/api/v1/Shipment?pageNumber=1&fromDate=&toDate=&searchString=null&newestFirst=false' \
--header 'Authorization: ••••••'

Response fields:

Root Level

Field	Type	Description
`results`	`array`	List of shipment objects.
`pageSize`	`integer`	Number of records returned per page.
`totalResults`	`integer`	Total number of matching shipments.
`totalPages`	`integer`	Total pages available.
`currentPage`	`integer`	Current page index.

Shipment Object (`results[]`)

Field	Type	Description
`id`	`string`	Unique identifier of the shipment.
`accountId`	`string`	Account ID associated with the shipment.
`relatedShipmentId`	`string`	ID of the related shipment (e.g., return shipment).
`locationId`	`string`	ID of the origin location.
`manifestId`	`string`	ID of the manifest linked to the shipment.
`trackingNumber`	`string`	Primary tracking number.
`trackingUrl`	`string`	Tracking page URL for the shipment.
`processedStatus`	`string`	Current processed status (e.g., `PreTransit`).
`processedStatusCode`	`string`	Code representing the processed status.
`status`	`string`	Shipment status (e.g., `Confirmed`, `Delivered`).
`paymentType`	`string`	Type of payment (e.g., `Prepaid`, `COD`).
`isTest`	`boolean`	Indicates if this is a test shipment.
`type`	`string`	Shipment type (`Forward`, `Return`).
`createdDate`	`string`	Timestamp when the shipment was created.
`transactionId`	`string`	Transaction ID related to this shipment.

Address Object (Used in addressFrom, addressShipTo, addressBillTo, addressReturn, addressAdditional)

Field	Type	Description
`id`	`string`	Address ID.
`save`	`boolean`	Whether the address should be saved.
`firstName`	`string`	Contact first name.
`lastName`	`string`	Contact last name.
`company`	`string`	Company or business name.
`street1`	`string`	Primary street address.
`street2`	`string`	Secondary address line.
`street3`	`string`	Tertiary address line.
`city`	`string`	City name.
`stateCode`	`string`	State code (e.g., DL, MH).
`zip`	`string`	Postal code.
`countryCode`	`string`	Country code (ISO).
`phone`	`string`	Contact phone number.
`phoneCode`	`string`	Country calling code.
`verify`	`boolean`	Whether the address is verified.
`category`	`string`	Address category (`Commercial` or `Residential`).
`email`	`string`	Contact email.
`latitude`	`number`	Latitude coordinate.
`longitude`	`number`	Longitude coordinate.

Packages Object (`packages[]`)

Field	Type	Description
`packageId`	`string`	Unique package identifier.
`packageNumber`	`integer`	Sequence number of the package.
`packageName`	`string`	Name or type of package.
`length`	`number`	Length of the package.
`width`	`number`	Width of the package.
`height`	`number`	Height of the package.
`weight`	`number`	Weight of the package.
`finalPackageType`	`string`	Final package type (e.g., `Box`).
`finalWeightUnit`	`string`	Weight unit (e.g., `kg`, `oz`).
`finalDimensionUnit`	`string`	Dimension unit (e.g., `cm`, `in`).
`finalWeight`	`number`	Final calculated weight.
`finalVolume`	`number`	Final calculated volume.
`oversized`	`boolean`	Indicates if the package is oversized.
`isMaster`	`boolean`	Marks the master package in a shipment.

Items Object (`items[]`)

Field	Type	Description
`id`	`string`	Unique item ID.
`productName`	`string`	Name of the product.
`sku`	`string`	SKU code.
`quantity`	`integer`	Quantity of items.
`weight`	`number`	Item weight.
`value`	`number`	Unit value of the item.
`totalValue`	`number`	Total value of all units.
`hsnCode`	`string`	HSN code.
`originCountry`	`string`	Country of origin.
`category`	`string`	Product category.
`taxInfos`	`array`	Tax details (code and value).

Rate Object (`rate`)

Field	Type	Description
`totalFee`	`number`	Total fee charged.
`valueCurrency`	`string`	Currency of fee.
`deliveryDaysEstimated`	`integer`	Estimated delivery days.
`deliveryDateEstimated`	`string`	Estimated delivery date.
`carrier`	`string`	Carrier name.
`service`	`string`	Carrier service name.
`categories`	`array`	Rate categories (`Cheapest`, `Fastest`).
`specialServices`	`array`	Applied special services (e.g., `COD`).

Tracking Object (`trackings[]`)

Field	Type	Description
`trackingBarcodeNumber`	`string`	Tracking number assigned to the package.
`trackingUrl`	`string`	URL for live tracking.
`processedStatusID`	`string`	Status ID (`PreTransit`, `Delivered`).
`isMaster`	`boolean`	Indicates if this is the master tracking.

Refund Object (`refund`)

Field	Type	Description
`status`	`string`	Refund status (`Rejected`, `Approved`).
`transactionDate`	`string`	Date of refund transaction.
`reason`	`string`	Reason for refund.

Date Object (`date`)

Field	Type	Description
`shipDate`	`string`	Actual ship date.
`pickupDate`	`string`	Actual pickup date.
`deliveryDate`	`string`	Actual delivery date.
`deliveryDateEstimated`	`string`	Estimated delivery date.
`returnDeliveryDate`	`string`	Return delivery date.

Response example:

{
  "results": [
    {
      "id": "string",
      "accountId": "string",
      "relatedShipmentId": "string",
      "addressFrom": { /* ... */ },
      "addressShipTo": { /* ... */ },
      "locationId": "string",
      "order": { /* ... */ },
      "packages": [ /* ... */ ],
      "items": [ /* ... */ ],
      "rate": { /* ... */ },
      "date": { /* ... */ },
      "manifestId": "string",
      "labels": [ /* ... */ ],
      "trackings": [ /* ... */ ],
      "trackingNumber": "string",
      "processedStatus": "PreTransit",
      "status": "Confirmed",
      "refund": { /* ... */ },
      "paymentType": "Prepaid",
      "type": "Forward",
      "customsDeclaration": { /* ... */ },
      "createdDate": "2025-10-16T13:25:40.035Z",
      "transactionId": "string"
    }
  ],
  "pageSize": 20,
  "totalResults": 100,
  "totalPages": 5,
  "currentPage": 1
}

GET: Shipment by Id

The GET Shipment by Id API endpoint for retrieving shipment information allows you to fetch detailed information about a specific shipment using its unique ID. The response provides comprehensive details about the shipment, including addresses, packages, rates, labels, and more. Use the provided request example and response format to integrate this API into your application for seamless shipment tracking and management.

Endpoint details:

Method	POST
Production Environment URL	https://api.kloudship.com/api/v1/Shipment/{id}
Test Environment URL	https://api-ppd.kloudship.com:960/api/v1/Shipment/{id}
Content-Type	application/json

Path variable:

Parameter	Type	Required	Description	Example
Id	string	Yes	This id can be Tracking id /Shipment id / Transaction id / TrackingNumber / Tracking Barcode Number	151730780008322

Query parameters:

Parameter	Type	Required	Description	Example
shipmentIdType	string	Yes	Specifies the type of tracking ID. Possible values: I`d, ShipmentId, TransactionId, TrackingNumber, TrackingBarcodeNumber`	TrackingNumber

Example cURL:

curl --location 'https://api-ppd.kloudship.com:960/api/v1/Shipment/151730780007610?shipmentIdType=TrackingNumber' \
--header 'transactionId: 354365' \
--header 'Authorization: ••••••'

Response fields:

Shipment Object

Field	Type	Description
`id`	`string`	Unique identifier of the shipment.
`accountId`	`string`	Account ID associated with the shipment.
`relatedShipmentId`	`string`	ID of the related shipment (e.g., return shipment).
`locationId`	`string`	ID of the origin location.
`manifestId`	`string`	ID of the manifest linked to the shipment.
`trackingNumber`	`string`	Primary tracking number.
`trackingUrl`	`string`	Tracking page URL for the shipment.
`processedStatus`	`string`	Current processed status (e.g., `PreTransit`).
`processedStatusCode`	`string`	Code representing the processed status.
`status`	`string`	Shipment status (e.g., `Confirmed`, `Delivered`).
`paymentType`	`string`	Type of payment (e.g., `Prepaid`, `COD`).
`isTest`	`boolean`	Indicates if this is a test shipment.
`type`	`string`	Shipment type (`Forward`, `Return`).
`createdDate`	`string`	Timestamp when the shipment was created.
`transactionId`	`string`	Transaction ID related to this shipment.

Address Object (Used in addressFrom, addressShipTo, addressBillTo, addressReturn, addressAdditional)

Field	Type	Description
`id`	`string`	Address ID.
`save`	`boolean`	Whether the address should be saved.
`firstName`	`string`	Contact first name.
`lastName`	`string`	Contact last name.
`company`	`string`	Company or business name.
`street1`	`string`	Primary street address.
`street2`	`string`	Secondary address line.
`street3`	`string`	Tertiary address line.
`city`	`string`	City name.
`stateCode`	`string`	State code (e.g., DL, MH).
`zip`	`string`	Postal code.
`countryCode`	`string`	Country code (ISO).
`phone`	`string`	Contact phone number.
`phoneCode`	`string`	Country calling code.
`verify`	`boolean`	Whether the address is verified.
`category`	`string`	Address category (`Commercial` or `Residential`).
`email`	`string`	Contact email.
`latitude`	`number`	Latitude coordinate.
`longitude`	`number`	Longitude coordinate.

Packages Object (`packages[]`)

Field	Type	Description
`packageId`	`string`	Unique package identifier.
`packageNumber`	`integer`	Sequence number of the package.
`packageName`	`string`	Name or type of package.
`length`	`number`	Length of the package.
`width`	`number`	Width of the package.
`height`	`number`	Height of the package.
`weight`	`number`	Weight of the package.
`finalPackageType`	`string`	Final package type (e.g., `Box`).
`finalWeightUnit`	`string`	Weight unit (e.g., `kg`, `oz`).
`finalDimensionUnit`	`string`	Dimension unit (e.g., `cm`, `in`).
`finalWeight`	`number`	Final calculated weight.
`finalVolume`	`number`	Final calculated volume.
`oversized`	`boolean`	Indicates if the package is oversized.
`isMaster`	`boolean`	Marks the master package in a shipment.

Items Object (`items[]`)

Field	Type	Description
`id`	`string`	Unique item ID.
`productName`	`string`	Name of the product.
`sku`	`string`	SKU code.
`quantity`	`integer`	Quantity of items.
`weight`	`number`	Item weight.
`value`	`number`	Unit value of the item.
`totalValue`	`number`	Total value of all units.
`hsnCode`	`string`	HSN code.
`originCountry`	`string`	Country of origin.
`category`	`string`	Product category.
`taxInfos`	`array`	Tax details (code and value).

Rate Object (`rate`)

Field	Type	Description
`totalFee`	`number`	Total fee charged.
`valueCurrency`	`string`	Currency of fee.
`deliveryDaysEstimated`	`integer`	Estimated delivery days.
`deliveryDateEstimated`	`string`	Estimated delivery date.
`carrier`	`string`	Carrier name.
`service`	`string`	Carrier service name.
`categories`	`array`	Rate categories (`Cheapest`, `Fastest`).
`specialServices`	`array`	Applied special services (e.g., `COD`).

Trackings Object (`trackings[]`)

Field	Type	Description
`trackingBarcodeNumber`	`string`	Tracking number assigned to the package.
`trackingUrl`	`string`	URL for live tracking.
`processedStatusID`	`string`	Status ID (`PreTransit`, `Delivered`).
`isMaster`	`boolean`	Indicates if this is the master tracking.

Refund Object (`refund`)

Field	Type	Description
`status`	`string`	Refund status (`Rejected`, `Approved`).
`transactionDate`	`string`	Date of refund transaction.
`reason`	`string`	Reason for refund.

Date Object (`date`)

Field	Type	Description
`shipDate`	`string`	Actual ship date.
`pickupDate`	`string`	Actual pickup date.
`deliveryDate`	`string`	Actual delivery date.
`deliveryDateEstimated`	`string`	Estimated delivery date.
`returnDeliveryDate`	`string`	Return delivery date.

Response Example:

{
  "id": "151730780007610",
  "accountId": "68f0a950f452c6ae5889d0f1",
  "relatedShipmentId": null,
  "addressFrom": {
    "firstName": "John",
    "lastName": "Doe",
    "company": "JD Logistics",
    "street1": "123 Main Street",
    "city": "Delhi",
    "stateCode": "DL",
    "zip": "110001",
    "countryCode": "IN",
    "phone": "9876543210",
    "email": "john@example.com"
  },
  "addressShipTo": {
    "firstName": "Jane",
    "lastName": "Smith",
    "company": "Smith Enterprises",
    "street1": "456 Market Road",
    "city": "Mumbai",
    "stateCode": "MH",
    "zip": "400001",
    "countryCode": "IN",
    "phone": "9876500000",
    "email": "jane@example.com"
  },
  "packages": [
    {
      "packageId": "pkg-12345",
      "packageNumber": 1,
      "packageName": "Box",
      "length": 10,
      "width": 5,
      "height": 5,
      "weight": 2,
      "finalWeightUnit": "kg",
      "finalDimensionUnit": "cm",
      "isMaster": true
    }
  ],
  "rate": {
    "totalFee": 150,
    "carrier": "XpressBees",
    "service": "Surface",
    "deliveryDateEstimated": "2025-10-18T14:01:12.602Z"
  },
  "trackingNumber": "151730780007610",
  "trackingUrl": "https://www.xpressbees.com/shipment/tracking?awbNo=151730780007610",
  "processedStatus": "PreTransit",
  "status": "Confirmed",
  "createdDate": "2025-10-16T14:01:12.602Z",
  "transactionId": "354365"
}

POST: Create shipment

This documentation outlines the usage of the "Create Shipment" endpoint for the Kloudship API. The endpoint allows you to create a new shipment by sending a POST request with the required payload. Below are the details of the request and the response for the API.

Endpoint details:

Method	POST
Production Environment URL	https://api.kloudship.com/api/v1/Shipment
Test Environment URL	https://api-ppd.kloudship.com:960/api/v1/Shipment
Content-Type	application/json

Headers:

Header	Type	Required	Description
`Content-Type`	`string`	Yes	Must be `application/json`
`Authorization`	`string`	Yes	Bearer token for authentication
`transactionId`	`string`	No	Optional unique transaction identifier for tracking requests

Request fields:

Field	Type	Required	Description
`addressFrom`	object	Yes	Sender’s address details
`addressShipTo`	object	Yes	Receiver’s address details
`isBillToSameAsShipTo`	boolean	No	If true, billing address = shipping address
`addressBillTo`	object	No	Billing address if different
`addressReturn`	object	No	Return address
`addressAdditional`	object	No	Additional address (if any)
`packages`	array	Yes	List of packages to be shipped
`items`	array	Yes	Product/item details included in shipment
`label`	object	Yes	Label configuration (type, size, format)
`carrierAccountId`	string	Yes	Carrier account ID
`service`	string	Yes	Selected carrier service
`orderType`	string	No	Type of order (if applicable)
`specialServices`	array	No	Special add-ons like insurance, COD, etc.
`customsDeclaration`	object	No	Required for international shipments
`locationId`	string	Yes	Origin warehouse or location ID
`isTest`	boolean	No	Use `true` for sandbox/testing mode

Request example:

{
    "addressFrom": {
        "firstname": "Nisha",
        "lastname": "Thuwal",
        "company": "Bharti Creations",
        "street1": "Bharti Creations, Gaon Bhag",
        "street2": "",
        "city": "Sangli",
        "stateCode": "MH",
        "zip": "416416",
        "countryCode": "IN",
        "phone": "9354456354",
        "email": "mayank.thuwal@impledge.com",
        "save": false,
        "verify": false,
        "isResidential": false,
        "latitude": 16.8597981,
        "longitude": 74.5635889
    },
    "locationId": "678a3ea9c17c95b6756b00e5",
    "carrierAccountId": "670ca085323de7c806a1e654",
    "service": "Surface",
    "addressShipTo": {
        "firstname": "Mayank",
        "lastname": "Thuwal",
        "company": "Impledge Technologies",
        "street1": "5TH FLOOR, REGUS, TOWER C",
        "street2": "Green Boulevard, B-BLOCK",
        "city": "Gautam Buddha Nagar",
        "stateCode": "UP",
        "zip": "201309",
        "countryCode": "IN",
        "phone": "9354456354",
        "email": "mayank.thuwal@impledge.com",
        "save": false,
        "verify": true,
        "isResidential": false,
        "latitude": 28.6228797,
        "longitude": 77.3672554
    },
    "packages": [
        {
            "name": "Watch Box",
            "length": 10.0,
            "width": 10.0,
            "height": 5.0,
            "dimensionUnit": "cm",
            "weight": 1.64,
            "weightUnit": "kg"
        }
    ],
    "items": [
        {
            "productId": "58712aebe8f048ec902bcc6c2d06426c",
            "productName": "Used Watch",
            "name": "Used Watch",
            "weight": 1000.0,
            "weightUnit": "g",
            "totalValue": 599.0,
            "value": 500.0,
            "taxInfos": [
                { "code": "IGST", "value": "99" }
            ]
        }
    ],
    "label": {
        "labelFileType": "PDF",
        "labelSize": "4x6",
        "labelOrientation": "Portrait",
        "labelType": "Url",
        "customText1": "Handle carefully",
        "customText2": "Don't Ring Door Bell"
    },
    "specialServices": [
        {
            "code": "Insure",
            "parameters": [
                { "code": "Amount", "value": "50" }
            ]
        }
    ],
    "isTest": true
}

Example cURL:

curl --location 'https://api-ppd.kloudship.com:960/api/v1/Shipment' \
--header 'transactionId: e9ae06c4-be54-4eba-ad26-0e76a9ba9d4a' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw '{
  ...same as request body above...
}'

Response fields:

Field	Type	Description
`id`	string	Unique identifier of the shipment
`trackingNumber`	string	Assigned tracking number by carrier
`trackingUrl`	string	Carrier tracking page URL
`status`	string	Current shipment status (e.g., Confirmed)
`processedStatus`	string	Internal status code (e.g., PreTransit)
`addressFrom`	object	Sender details
`addressShipTo`	object	Recipient details
`packages`	array	Package dimensions and weight
`items`	array	Product-level details for shipment
`rate`	object	Billing details — total charges, currency, carrier info
`labels`	array	Label URLs and format
`date`	object	Shipping and delivery dates
`customsDeclaration`	object	Customs info for international shipments
`paymentType`	string	Payment mode (`Prepaid` or `COD`)
`isTest`	boolean	Indicates test mode
`errors`	array	List of validation or carrier errors (if any)
`createdDate`	string	Date when shipment was created
`transactionId`	string	Transaction reference ID

Response example:

{
  "id": "6745a01fba34f7f7b9271b10",
  "trackingNumber": "151730750000015",
  "trackingUrl": "https://www.xpressbees.com/shipment/tracking?awbNo=151730750000015",
  "status": "Confirmed",
  "processedStatus": "PreTransit",
  "rate": {
    "valueCurrency": "INR",
    "totalFee": 300.9,
    "carrier": "XpressBees",
    "service": "Surface"
  },
  "labels": [
    {
      "url": "https://s3.amazonaws.com/kloudship-labels/sample-label.pdf",
      "fileType": "PDF",
      "size": "4x6",
      "orientation": "Portrait"
    }
  ],
  "createdDate": "2025-10-16T14:13:57.570Z",
  "isTest": true
}

PUT: Shipment refund

The PUT Refund Shipment API allows you to initiate a refund for a specific shipment. This API is used to cancel a shipment and initiate the refund process. It requires the shipment ID and cancellation reason as input parameters.

Endpoint details:

Method	POST
Production Environment URL	https://api.kloudship.com/api/v1/Shipment/{id}/refund
Test Environment URL	https://api-ppd.kloudship.com:960/api/v1/Shipment/{id}/Refund
Content-Type	application/json

Header:

Header	Type	Required	Description
`Content-Type`	`string`	Yes	Must be `application/json`
`Authorization`	`string`	Yes	Bearer token for authentication
`transactionId`	`string`	Yes	Optional unique identifier for tracking this refund request

Path parameter

Parameter	Type	Required	Description
`shipmentId`	`string`	Yes	Unique ID of the shipment for which the refund is being initiated

Request body:

{
  "CancelationReason": "Not interested"
}

Example cURL:

curl --location --request PUT 'https://api-ppd.kloudship.com:960/api/v1/Shipment/68f10000f452c6ae5889d1a0/Refund' \
--header 'transactionId: b9257979-5387-43c9-a47f-2df940added8' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "CancelationReason": "Not interested"
}'

Response fields:

Field	Type	Description
`status`	`string`	Refund request status — usually `"Initiated"`
`transactionDate`	`string (ISO 8601)`	Timestamp of when refund was initiated
`reason`	`string`	Reason provided during refund initiation

Example response:

{
  "status": "Initiated",
  "transactionDate": "2025-10-16T14:24:10.3683578Z",
  "reason": "Not interested"
}

API - Shipment

GET: Shipments

Endpoint details:

Query paramters:

Request body:

Example cURL:

Response fields:

Root Level

Shipment Object (results[])

Address Object (Used in addressFrom, addressShipTo, addressBillTo, addressReturn, addressAdditional)

Packages Object (packages[])

Items Object (items[])

Rate Object (rate)

Tracking Object (trackings[])

Refund Object (refund)

Date Object (date)

Response example:

GET: Shipment by Id

Endpoint details:

Path variable:

Query parameters:

Example cURL:

Response fields:

Shipment Object

Address Object (Used in addressFrom, addressShipTo, addressBillTo, addressReturn, addressAdditional)

Packages Object (packages[])

Items Object (items[])

Rate Object (rate)

Trackings Object (trackings[])

Refund Object (refund)

Date Object (date)

Response Example:

POST: Create shipment

Endpoint details:

Headers:

Request fields:

Request example:

Example cURL:

Response fields:

Response example:

PUT: Shipment refund

Endpoint details:

Header:

Path parameter

Request body:

Example cURL:

Response fields:

Example response:

Shipment Object (`results[]`)

Packages Object (`packages[]`)

Items Object (`items[]`)

Rate Object (`rate`)

Tracking Object (`trackings[]`)

Refund Object (`refund`)

Date Object (`date`)

Packages Object (`packages[]`)

Items Object (`items[]`)

Rate Object (`rate`)

Trackings Object (`trackings[]`)

Refund Object (`refund`)

Date Object (`date`)