API - Shipment

Created by KloudShip Support, Modified on Fri, 8 Mar, 2024 at 7:04 PM by KloudShip Support

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

POST /{{BaseURL}}/Shipment

Request Headers

`transactionId` (string, required): A unique identifier for the transaction.
`Content-Type` (string, required): Set to `application/json`.
`Authorization` (string, required): Bearer token obtained through authentication.

Request Body

The payload must be a JSON object containing the following parameters:

`addressFrom` (object, required): Information about the sender's address.
`addressShipTo` (object, required): Information about the recipient's address.
`packages` (array of objects, required): Array of package details.
`locationId` (string, required): ID of the location.
`carrierAccountId` (string, required): ID of the carrier account.
`service` (string, required): Service type for the shipment.
`label` (object, required): Label specifications.
`items` (array of objects, required): Array of items in the shipment.
`valueAmount` (number, required): Shipment value amount.

Example request payload

{
    "addressFrom": { ... },
    "addressShipTo": { ... },
    "packages": [ ... ],
    "locationId": "647da3c9d40010c2318c59a9",
    "carrierAccountId": "64cc9ac67a2876f1b3244142",
    "service": "Surface",
    "label": { ... },
    "items": [ ... ],
    "valueAmount": 12
}

Response Body

Upon a successful request, you will receive a JSON response containing details about the created shipment:

`id` (string): Shipment ID.
`addressFrom` (object): Sender's address details.
`addressShipTo` (object): Recipient's address details.
`packages` (array): Array of package details.
`rate` (object): Rate details.
`label` (object): Label information.
`trackingNumber` (string): Tracking number for the shipment.
`trackingUrl` (string): Tracking URL for the shipment.
`status` (string): Shipment status.
`shipDate` (string): Shipment date and time.
`errors` (array): Array of errors, if any.
`createdDate` (string): Date and time of shipment creation.
`transactionId` (string): Transaction ID.

Example response

{
    "id": "64ddfc982e3464d34bfc984c",
    "addressFrom": { ... },
    "addressShipTo": { ... },
    "packages": [ ... ],
    "rate": { ... },
    "label": { ... },
    "trackingNumber": "5871310010275",
    "trackingUrl": "https://www.delhivery.com/track/package/5871310010275",
    "status": "PreTransit",
    "shipDate": "2023-08-17T10:55:18.0025728Z",
    "errors": [],
    "createdDate": "2023-08-17T10:55:22.8163562Z",
    "transactionId": "ad2248e7-6d20-40e9-a608-91f2a8f97e24"
}

GET: Shipment

The Kloudship 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

GET /{{BaseURL}}/Shipment/{shipment_id}

Example Response

{
    "id": "64ba579b691f3561551578d8",
    "addressFrom": { ... },  # Sender address details
    "addressShipTo": { ... },  # Recipient address details
    "addressBillTo": { ... },  # Billing address details
    "packages": [ ... ],  # Package information
    "rate": { ... },  # Shipping rate details
    "label": { ... },  # Label information
    "forms": [],  # Forms associated with the shipment
    "status": "PreTransit",  # Shipment status
    "refundStatus": "Refunded",  # Refund status
    "shipDate": "2023-07-21T10:02:00.91Z",  # Shipment date
    "errors": [],  # Any errors associated with the shipment
    "createdDate": "2023-07-21T10:02:05.238Z"  # Shipment creation date
}

Response Description

`id`: Unique identifier of the shipment.
`addressFrom`: Sender's address information.
`addressShipTo`: Recipient's address information.
`addressBillTo`: Billing address information.
`packages`: Array of package details in the shipment.
`rate`: Shipping rate and carrier details.
`label`: Label information for the shipment.
`forms`: Forms associated with the shipment.
`status`: Current status of the shipment.
`refundStatus`: Refund status of the shipment.
`shipDate`: Shipment date and time.
`errors`: Any errors associated with the shipment.
`createdDate`: Date and time when the shipment was created.

PUT: Refund Shipment

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.

Request

{
     "CancelationReason": "{cancellationReason}"
}

Request Headers

`transactionId` (required): A unique identifier for the API request.
`Content-Type` (required): Set to `application/json`.
`Authorization` (required): A bearer token for authentication.

Request Body

- `CancelationReason` (required): A string indicating the reason for canceling the shipment.

Response

{
    "id": "{shipmentId}",
    "addressFrom": {
        // Details of the sender's address
    },
    "addressShipTo": {
        // Details of the recipient's address
    },
    "addressBillTo": {
        // Details of the billing address
    },
    "rate": {
        // Shipping rate and fee details
    },
    "label": {
        // Label information
    },
    "forms": [],
    "status": "PreTransit",
    "refundStatus": "Refunded",
    "shipDate": "2023-08-17T10:55:18.002Z",
    "errors": [],
    "createdDate": "2023-08-17T10:55:22.816Z",
    "transactionId": "{transactionId}"
}

Response Fields

`id`: The ID of the refunded shipment.
`addressFrom`: Details of the sender's address.
`addressShipTo`: Details of the recipient's address.
`addressBillTo`: Details of the billing address.
`rate`: Shipping rate and fee details.
`label`: Label information including label URLs.
`forms`: Array of forms associated with the shipment (if applicable).
`status`: Current status of the shipment (e.g., "PreTransit").
`refundStatus`: Refund status indicating whether the refund process was successful ("Refunded").
`shipDate`: Date and time of shipment.
`errors`: Array of error messages (if any).
`createdDate`: Date and time when the shipment was created.
`transactionId`: Unique identifier for the API transaction.

PUT: Shipment Tracking

The Shipment Tracking API allows you to retrieve tracking information for a specific shipment using its unique identifier. This API provides details about the current status, carrier information, tracking numbers, and other relevant information related to the shipment.

Endpoint

GET {{BaseUrl}}/Tracking/{shipment_Id}

Response

Upon a successful request, the API will respond with the tracking information for the specified shipment in the following JSON format:

{
    "id": "64ddfc9a2e3464d34bfc984d",
    "shipmentId": "64ddfc982e3464d34bfc984c",
    "carrierAccountName": "Delhivery",
    "carrier": "Delhivery",
    "trackingBarcodeNumber": "5871310010275",
    "trackingNumber": "5871310010275",
    "status": "Cancelled",
    "subStatus": "LabelGenerated",
    "trackingUrl": "https://www.delhivery.com/track/package/5871310010275",
    "trackingDetails": [],
    "errors": []
}

Response Fields

`id`: The unique identifier for the tracking information.
`shipmentId`: The unique identifier of the shipment being tracked.
`carrierAccountName`: The name of the carrier account associated with the shipment.
`carrier`: The name of the carrier responsible for shipping.
`trackingBarcodeNumber`: The barcode number associated with the shipment's tracking.
`trackingNumber`: The tracking number assigned to the shipment.
`status`: The current status of the shipment (e.g., "Cancelled", "In Transit", etc.).
`subStatus`: Additional status information or sub-status (e.g., "LabelGenerated").
`trackingUrl`: URL to the carrier's tracking page for the shipment.
`trackingDetails`: An array of tracking details (if available).
`errors`: An array of errors (if any).