Pickup Request: Rest of the World

Overview

This is a new version of Pickup API, which takes in certain details of an 'open' shipment in the carrier's database ('Open' shipments refer to those for which the pickup_time value has not been defined yet) and places a pickup request in the carrier's server.

This will be very helpful for reverse pickup customers to raise the pickup again for a particular shipment especially for global carrier partners like DHL and geographies like Europe and North America.

Important Links

Usecase

This is a standard API which applies to MPS (Multi-Piece Shipment) and SPS (Single Piece Shipment) orders which are open (where pickup_time is not defined but are saved in carrier's database) and placed with DHL International (Partner ID: 145) as of 9th Decembeer 2022.

Geography

Shipments created and transported in
- North America
- Europe
- Middle East
- South East Asia
Cross-Border shipments: Shipments that are to be transported from India to any other country in the aforementioned regions, or vice versa

Path

POST <https://www.clickpost.in/api/v2/create-pickup/>

Payload

The payload may consist of the following objects

Field Name	Data Type	Field	Description	Max Length	Example
`shipment_details`	Object	Mandatory	Details of the shipment to generate the pickup request for
`pickup_info`	Object	Mandatory	Information of the location of pickup

`shipment_details` Object

The following fields can be a part of the shipment_details object.

Field Name	Data Type	Field	Description	Max Length	Example
`reference_number`	String	Optional	Reference number of the shipment. This reference Number is for logging purposes, can be used to request logs using this field	100	"TESTREF00001"
`awb_number`	String	Mandatory	AWB number of the shipment	100	"TESTAWB00001"
`courier_partner_id`	String	Mandatory	Partner ID of the carrier responsible for the pickup		123
`account_code`	String	Mandatory	Courier partner account name configured on the Clickpost dashboard		"test_account"
`items`	List[Object]	Optional	List of items for which the pickup is to be initiated
`height`	Float	Conditional	Height of the overall shipment (in cm). To be passed if `items` is passed		25.2
`breadth`	Float	Conditional	Breadth of the overall shipment (in cm). To be passed if `items` is passed		25
`length`	Float	Conditional	Length of the overall shipment (in cm). To be passed if `items` is passed		25
`weight`	Float	Conditional	Weight of the overall shipment (in gram). To be passed if `items` is passed		25

`pickup_info` Object

Field Name	Data Type	Field	Description	Max Length	Example
`name`	String	Optional	Contact name of the consignor of the shipment. If not provided, will be picked up from RVP payload.	100	"Mukesh Kumar"
`address`	String	Optional	Address of the pickup location. If not provided, will be picked up from RVP payload.	500	"123, ABC Street"
`city`	String	Optional	City of the pickup location If not provided, will be picked up from RVP payload.	100	"Mumbai City"
`state`	String	Optional	State/province of the pickup location If not provided, will be picked up from RVP payload.	100	"Maharashtra"
`email`	String	Optional	Email of the pickup contact If not provided, will be picked up from RVP payload.	50	"[email protected]"
`phone`	String	Optional	Contact number of the pickup contact If not provided, will be picked up from RVP payload.	11	"9876543210"
`start_time`	String	Optional	Time when pickup should be initiated (to be provided in HH:MM format only)	6	"10:22"
`end_time`	String	Optional	Time by when pickup should be completed (to be provided in HH:MM format only) If not provided, this will be assumed to be 2 hours after `start_time`	6	"12:22"
`postal_code`	String	Optional	Postal code of the pickup location If not provided, will be picked up from RVP payload.	6	"400065"
`country`	String	Optional	Alpha ISO-2 country code of the pickup location. If not provided, will be picked up from RVP payload.	2	"IN"

`items` List

The items field will be a list of objects containing the following fields

Field Name	Data Type	Field	Description	Max Length	Example
`description`	String	Optional	Brief description of the item If not provided, will be picked up from RVP payload.	500	"Brown Cotton Socks - 1 pair"
`quantity`	Integer	Optional	Number of units of the item If not provided, will be picked up from RVP payload.		5
`weight`	Float	Optional	Weight of each unit of the item If not provided, will be picked up from RVP payload.		500
`price`	Float	Optional	Price of each unit of the item (currency to be decided by 'currency_code' field) If not provided, will be picked up from RVP payload.		64.99
`sku`	String	Mandatory	Stock-keeping unit of the item If not provided, will be picked up from RVP payload.	100	"SKU0001"
`height`	Float	Optional	Height of the item (in cm). If not provided, will be picked up from RVP payload.		25.2
`breadth`	Float	Optional	Breadth of the item (in cm). If not provided, will be picked up from RVP payload.		25.2
`length`	Float	Optional	Length of the item (in cm). If not provided, will be picked up from RVP payload.		25.2

Response

The response may contain the following fields

Field Name	Data Type	Description
`meta`	Object	Metadata for the request, e.g. status code, error messages.
`result`	Object	Actual result of the request

Response Meta

Field Name	Data Type	Description
`status`	Integer	Status code for the request (including but not limited to HTTP Status codes)
`message`	String/Object	Error/Success messages for the request. Can also be an object containing all the errors
`success`	Boolean	Whether the order was successfully created or not

Response Result

Field Name	Data Type	Description
`confirmation_number`	String	Confirmation number of the pickup request

Sample Payload

{
    "shipment_details": {
        "reference_number": "TestDHLME000001",
        "awb_number": "6276148141",
        "courier_partner_id": 159,
        "account_code": "1",
        "items": [
            {
                "sku": "S159SV8TAUXL",
                "price": 85.12,
                "weight": 2,
                "quantity": 1,
                "description": "Recycled Flared Legging - Regular",
                "height": 1,
                "length": 1,
                "breadth": 1
            }
        ],
        "height": 1,
        "length": 1,
        "weight": 10,
        "breadth": 1
    },
    "pickup_info": {
        "date": "2022-11-11",
        "start_time": "10:45",
        "end_time": "11:05",
        "email": "[email protected]",
        "phone":"8080808080",
        "phone_code": "+91",
        "name": "Warehouse Pickup POC",
        "address": "Test Pickup Warehouse Address, Pickup Locality, ",
        "city": "Test City",
        "state": "ABCD",
        "country_code":"IN",
        "postal_code": 123456
    }
}

Sample Response

{
    "meta": {
        "message": "SUCCESS",
        "success": true,
        "status": 200
    },
    "result": {
        "confirmation_number": "CBJ221111679550"
    }
}

{
    "meta": {
        "status": 400,
        "message": {
            "non_field_errors": [
                "627618141 not registered against account code 1"
            ]
        },
        "success": false
    }
}

{
    "meta": {
        "status": 400,
        "message": {
            "non_field_errors": [
                ": invalid Account Code 8"
            ]
        },
        "success": false
    }
}