Guides
Home

Create/Update a Shipment

Suggest Edits

This endpoint is used to create a new shipment. The request must include sender and receiver details, shipment information, and item details. Upon successful creation, the API returns the shipment details along with a 201 Created status.

Endpoint: POST /api/v1/shipment/create

Request

  • URL: /api/v1/shipment/create
  • Method: POST
  • Content-Type: application/json
  • Authentication: Bearer token required in the Authorization header.

Headers:

Authorization: Bearer {jwt_token}
Content-Type: application/json

Sample Payload:

{
    "trackingNumber": "TRACK1234567890",
    "sender": {
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "+11234567890",
        "secondPhone": "+11234567891",
        "countryCode": "US",
        "state": "California",
        "postCode": "90210",
        "city": "Beverly Hills",
        "line1": "1234 Elm Street",
        "line2": "Apt 101",
        "line3": ""
    },
    "receiver": {
        "name": "Jane Smith",
        "email": "[email protected]",
        "phone": "+442071234567",
        "secondPhone": "+442071234568",
        "countryCode": "GB",
        "state": "London",
        "postCode": "SW1A 1AA",
        "city": "London",
        "line1": "10 Downing Street",
        "line2": "",
        "line3": ""
    },
    "details": {
        "weight": {
            "unit": "KG",
            "value": 10.0
        },
        "declaredWeight": {
            "unit": "KG",
            "value": 10.0
        },
        "cod": {
            "currencyCode": "USD",
            "amount": 100.00
        },
        "customs": {
            "currencyCode": "GBP",
            "amount": 150.00
        },
        "deliveryCharges": {
            "currencyCode": "USD",
            "amount": 50.00
        },
        "numberOfPieces": 1,
        "pickupDate": "2024-09-11T06:40:49.160Z",
        "deliveryStatus": "In Transit",
        "deliveryDate": "2024-09-15T10:30:00Z",
        "deliveryAttempts": 1,
        "shippingType": "INT",
        "productCategory": "Electronics",
        "productType": "Parcel",
        "descriptionOfGoods": "Smartphones",
        "dimensions": {
            "length": 50.0,
            "width": 30.0,
            "height": 20.0,
            "unit": "CM"
        }
    },
    "items": [
        {
            "description": "iPhone 14",
            "countryOfOrigin": "CN",
            "quantity": 1,
            "hsCode": "851712",
            "customsValue": {
                "currencyCode": "USD",
                "amount": 1500.00
            },
            "weight": {
                "unit": "KG",
                "value": 1.5
            },
            "dimensions": {
                "length": 15.0,
                "width": 7.0,
                "height": 0.7,
                "unit": "CM"
            }
        }
    ]
}

Request Parameters:

  • trackingNumber (string): The unique tracking number associated with the shipment.
  • sender (object): The sender details, including:
    • name (string): The name of the person or company sending the shipment.
    • phone (string): The sender's phone number in international format.
    • countryCode (string): The ISO 3166-1 alpha-2 country code of the sender's address.
    • city (string): The city of the sender's address.
    • line1 (string): The first line of the sender's address (e.g., street name and number).
  • receiver (object): The receiver details, including:
    • name (string): The name of the person or company receiving the shipment.
    • phone (string): The receiver's phone number in international format.
    • countryCode (string): The ISO 3166-1 alpha-2 country code of the receiver's address.
    • city (string): The city of the receiver's address.
    • line1 (string): The first line of the receiver's address (e.g., street name and number).
  • details (object): Detailed information about the shipment, including:
    • weight (object): The weight provided by the customer or the volumetric or gross weight, whichever is higher, including:
      • unit (string): The unit of measurement for the weight (e.g., KG, LB).
      • value (number): The total weight value.
    • declaredWeight (object): The weight used for billing purposes to charge your customer, including:
      • unit (string): The unit of measurement for the declared weight (e.g., KG, LB).
      • value (number): The declared weight value.
    • numberOfPieces (integer): The total number of individual items or packages in the shipment.
    • pickupDate (string): The date when the shipment was collected (format: date-time).
    • shippingType (string): Specifies whether the shipment is Domestic or International (e.g., INT for International, DOM for Domestic).
    • productCategory (string): Defines the shipment category, such as Documents and Non-Documents.
    • productType (string): Represents the service level of the shipment, such as Non-Priority, Standard, Priority, Premium, Same Day, Next Day, etc.
    • descriptionOfGoods (string): Provides a detailed description of the items in the shipment.
    • hsCodeDescription (string): Describes the goods based on the Harmonized System (HS) code, used for international trade classification.
    • dimensions (object): The dimensions of the shipment, including:
      • length (number): The length of the shipment.
      • width (number): The width of the shipment.
      • height (number): The height of the shipment.
      • unit (string): The unit of measurement for the dimensions (e.g., CM, IN).
  • items (array of objects): A list of individual items in the shipment, each containing:
    • description (string): A brief description of the item (e.g., iPhone 14).
    • countryOfOrigin (string): The country where the item was manufactured (ISO 3166-1 alpha-2 country code).
    • quantity (number): The number of units of the specific item.
    • weight (object): The weight provided by the customer or the volumetric or gross weight, whichever is higher, including:
      • unit (string): The unit of measurement for the weight (e.g., KG, LB).
      • value (number): The weight value of the item.
    • dimensions (object): The dimensions of the individual item, similar to dimensions.
    • customsValue (object): The customs value of the item, including:
      • currencyCode (string): The three-letter ISO currency code (e.g., USD).
      • amount (number): The monetary amount for customs value.
  • cod (object, optional): The Cash on Delivery (COD) amount, including:
    • currencyCode (string): The three-letter ISO currency code (e.g., USD).
    • amount (number): The COD amount.
  • customs (object, optional): Customs charges for the shipment, including:
    • currencyCode (string): The three-letter ISO currency code (e.g., USD).
    • amount (number): The amount for customs charges.
  • deliveryCharges (object, optional): Delivery Charges for the shipment, including:
    • currencyCode (string): The three-letter ISO currency code (e.g., USD).
    • amount (number): The amount for customs charges.

Response

  • Status: 201 Created

Sample Response:

{
    "status": "Success",
    "message": "Shipment created successfully.",
    "data": {
        "trackingNumber": "TRACK1234567890",
        "sender": {
            "name": "John Doe",
            "email": "[email protected]",
            "phone": "+11234567890",
            "secondPhone": "+11234567891",
            "countryCode": "US",
            "state": "California",
            "postCode": "90210",
            "city": "Beverly Hills",
            "line1": "1234 Elm Street",
            "line2": "Apt 101",
            "line3": ""
        },
        "receiver": {
            "name": "Jane Smith",
            "email": "[email protected]",
            "phone": "+442071234567",
            "secondPhone": "+442071234568",
            "countryCode": "GB",
            "state": "London",
            "postCode": "SW1A 1AA",
            "city": "London",
            "line1": "10 Downing Street",
            "line2": "",
            "line3": ""
        },
        "details": {
            "weight": {
                "unit": "KG",
                "value": 10.0
            },
            "declaredWeight": {
                "unit": "KG",
                "value": 10.0
            },
            "cod": {
                "currencyCode": "USD",
                "amount": 100.00
            },
            "customs": {
                "currencyCode": "GBP",
                "amount": 150.00
            },
            "deliveryCharges": {
                "currencyCode": "USD",
                "amount": 50.00
            },
            "numberOfPieces": 1,
            "pickupDate": "2024-09-11T06:40:49.16Z",
            "deliveryStatus": "In Transit",
            "deliveryDate": "2024-09-15T10:30:00Z",
            "deliveryAttempts": 1,
            "shippingType": "INT",
            "productCategory": "Electronics",
            "productType": "Parcel",
            "descriptionOfGoods": "Smartphones",
            "dimensions": {
                "length": 50.0,
                "width": 30.0,
                "height": 20.0,
                "unit": "CM"
            }
        },
        "items": [
            {
                "description": "iPhone 14",
                "countryOfOrigin": "CN",
                "quantity": 1,
                "hsCode": "851712",
                "value": null,
                "weight": {
                    "unit": "KG",
                    "value": 1.5
                },
                "dimensions": {
                    "length": 15.0,
                    "width": 7.0,
                    "height": 0.7,
                    "unit": "CM"
                }
            }
        ]
    },
    "errors": null,
    "correlationId": "1f2b17c6-a560-48db-87f0-0f6836ec0d59",
    "timestamp": "2024-11-13T12:33:23.8214485Z"
}

Response Fields

  • status (string): Indicates whether the request was successful or failed. Possible values:

    • "success": The request was processed successfully.
    • "failure": The request failed due to an error.

  • message (string): A human-readable statement describing the result of the request. For example:

    • "Shipment created successfully."
    • "Invalid request parameters."

  • data (object, optional): Contains the data object that was submitted to the API in case of a successful request. For example, when creating a shipment, this will return the same ShipmentDto object.

  • errors (array of ErrorDto, optional): A list of detailed errors, provided when the request fails.

  • correlationId (string): A unique identifier assigned to the request for tracking purposes. This is useful for troubleshooting or auditing and will be generated for every request, whether successful or not.

  • timestamp (string): The date and time when the request was received and processed. The format is ISO 8601, for example: "2024-09-01T10:15:30Z".

Possible HTTP Status Codes

  • 201 Created: Shipment was successfully created/updated.
  • 400 Bad Request: Invalid input data (e.g., missing required fields, invalid format). You’ll receive details in the error response.
  • 401 Unauthorized: Missing or invalid authentication token.
  • 422 Unprocessable Entity: Data validation failed, such as invalid email or phone format.
  • 500 Internal Server Error: An error occurred on the server while processing the request.

Additional Notes

Rate Limiting: This endpoint is subject to rate limiting. Ensure your integration handles rate limits gracefully and retries requests when the 429 Too Many Requests response is received.

By following this guide, you'll be able to securely create a shipment in our platform.

Updated 2 months ago