ClickPost

ClickPost multi-carrier shipping API: username plus key query auth or a 24 hour token, with serviceability, AWB creation, label, pickup, tracking, POD and NDR.

ClickPost is an Indian multi-carrier logistics intelligence platform. It sits between a brand's order system and 300 or more courier partners, so that one integration covers Delhivery, Blue Dart, Ecom Express, XpressBees, Shadowfax, Ekart, India Post, Shiprocket and dozens of regional and international carriers. For a seller, ClickPost is the carrier abstraction layer: one request body creates an AWB on whichever carrier the recommendation engine picks, one tracking response normalises every carrier's scan vocabulary into a single status code, and one webhook stream carries every scan. It is sold to enterprises rather than self-serve, so credentials come from an onboarding manager, not a signup form.

At a glance

What it is

ClickPost (Vesreto Technologies) is a Delhi and Gurugram based logistics SaaS founded in 2015. Its own documentation describes it as serving 250 or more enterprises with pre built integrations to 300 or more couriers. The product has four parts: carrier allocation (a recommendation engine that picks a courier per order from business rules and historic performance), shipment manifestation (AWB and label generation across carriers), unified tracking with branded post purchase pages, and exception management (NDR workflows, WISMO reduction, returns and exchanges).

It is not a marketplace and does not hold inventory. In the unified model it is a source of shipments and returns only, and a very good one, because it is the single place where scans from many carriers are already normalised. A live carrier directory is published at carriers.clickpost.ai with per carrier capability filters such as proof of delivery, reverse pickup and quality check.

API access

Credentials are not self-serve. The getting started page states the documentation is for enterprises and that the username, key, and (for token auth) password come from the onboarding manager or the support team.

No public developer console and no published pricing for API access. Access follows a commercial contract.
Two base hosts are in use. The docs state that the base URL moved from https://www.clickpost.in to https://api.clickpost.in, with backward compatibility maintained on the old host. New integrations should use api.clickpost.in.
Versions in force at the time of reading: order creation v3 for India, v4 for international and cross border, tracking v2, serviceability v3 (with a v1 bulk variant), cancellation v1, pickup v2, recommendation v2.
No official SDK in any language is published. ClickPost publishes a Postman workspace instead, at postman.com/cptech/clickpost-api-documentation, and "Run in Postman" buttons on the serviceability, label and proof of delivery pages point at collection 23733811-8d3cc7d3-4204-47e1-ab76-b6132741961e.

Note

The docs site is the same ReadMe project under three hostnames. clickpost.readme.io redirects to docs.clickpost.ai. docs.clickpost.in returns a Cloudflare interstitial to non browser clients, so automated doc harvesting should target docs.clickpost.ai.

Authentication

There are two schemes. Both identify the enterprise account, not an individual seller, so multi account support means holding one credential set per ClickPost enterprise account.

Scheme 1: username and key in the query string

Every documented endpoint accepts username and key as query parameters. key is a UUID issued per enterprise, username is the enterprise username. There is no signature and no expiry.

curl -X GET \
  "https://api.clickpost.in/api/v2/track-order/?username=test-enterprise&key=34be9be5-3de8-4223-ad14-d7391159b80e&waybill=4210610508756&cp_id=25"

Scheme 2: token exchange

For enterprises that do not want long lived keys on the wire, ClickPost publishes a token endpoint.

POST the enterprise username and password to the token endpoint.
Read token and expires_at from the response. The token is valid for 24 hours.
Send the token in the header of subsequent API requests.
Refresh before expires_at. There is no refresh token, the same username and password call is repeated.

POST /api/v1/user/token/ HTTP/1.1
Host: www.clickpost.in
Content-Type: application/json

{
  "username": "test_username",
  "password": "some_strong_password"
}

{
  "token": "1123123123123123106",
  "expires_at": "2025-03-28T11:12:07"
}

The exact header name for presenting the token is shown only as a screenshot in the docs and is not written out in text, so treat the header spelling as unverified and confirm it with the onboarding team. Scopes and roles are not published: a key is enterprise wide.

Objects we can read

ClickPost has no orders-as-commerce, no listings and no inventory. What it exposes is the shipment lifecycle.

Orders

GET https://api.clickpost.in/api/v1/updated-order returns shipments updated inside a time window, which is the delta read for a warehouse sync.

There is also an order detail read, documented as "Get order details for v3 API" and "Get order details for v4 API", and a matching push route "Order details via webhook". Pagination for the updated order list is by time window rather than cursor: advance start_date to the last seen update time.

Shipments and tracking

GET https://api.clickpost.in/api/v2/track-order/?username=...&key=...&waybill=...&cp_id=...

waybill accepts up to 5 comma separated AWBs in one call, provided all belong to the same carrier. cp_id is the ClickPost courier partner id. The response carries latest_status and the full scans history, with both the raw carrier status and the normalised ClickPost code.

{
  "meta": { "status": 200, "success": true, "message": "SUCCESS" },
  "result": {
    "4210610508756": {
      "latest_status": {
        "timestamp": "2022-10-31 19:56:16",
        "location": "Faridabad_Mthurard_CP (Haryana)",
        "remark": "Shipment not received from client",
        "status": "Not Picked",
        "clickpost_status_code": 2,
        "clickpost_status_description": "PickupPending",
        "clickpost_status_bucket": 1,
        "clickpost_status_bucket_description": "Order Placed",
        "created_at": "2022-10-27 11:10:28"
      },
      "scans": [
        {
          "timestamp": "2022-10-31 19:56:16",
          "location": "Faridabad_Mthurard_CP (Haryana)",
          "remark": "Shipment not received from client",
          "status": "Not Picked",
          "clickpost_status_code": 2,
          "checkpoint_id": 9629321255,
          "tracking_id": 493656670,
          "created_at": "2022-10-31 15:30:31",
          "clickpost_status_description": "PickupPending",
          "clickpost_status_bucket": 1,
          "clickpost_status_bucket_description": "Order Placed"
        }
      ]
    }
  }
}

clickpost_status_code and clickpost_status_bucket are the fields to key business logic on. The full code table is published at tracking status codes. Buckets seen in samples include 1 Order Placed and 6 Delivered.

Proof of delivery

GET https://api.clickpost.in/api/v1/pod/pod_from_shipment_details/ with key and waybill. The response returns an S3 URL to a POD PDF. Only carriers flagged "Proof of Delivery [POD]" in the carrier directory support it.

Returns and cancellations

Returns delta read: a returns polling API is documented as "Returns polling delta API", which lists return shipments changed in a window.
Return creation is the same order creation endpoint with shipment_details.delivery_type set to RVP and additional.rvp_reason populated, on a carrier that supports reverse pickup. Reverse with quality check is a separate documented variant.
A "Return order placed" webhook pushes new return shipments.

NDR

NDR is exposed as status codes plus an NDR action update API that writes the seller's instruction (reattempt, change address, change phone) back to the carrier. The docs give the NDR and NPR status code tables but describe the action API narratively rather than with a published path, so confirm the route during onboarding.

Serviceability and rate shopping

POST /api/v3/serviceability_api/ on https://serviceability.clickpost.in, request body keyed on drop_pincode, optionally with the pickup pincode and service_type (FORWARD is assumed if omitted). The response exposes a serviceable flag per carrier and which of COD, PREPAID and EXCHANGE are available.
POST /api/v1/bulk_serviceability_api/ for batches.
POST https://www.clickpost.in/api/v2/recommendation/ returns carriers in priority order for an order, which is the rate and SLA shopping call.
An expected date of delivery API returns a predicted SLA range for a shipment.

Reporting

A report request API plus a status endpoint produce asynchronous extracts (request a report, poll for its status and data). Field lists are published for the NDR shipment, NDR communication and return tracking dashboard report schemas. This is the route for bulk historical pulls rather than the per shipment APIs.

Not available

No products, listings, inventory, customers or settlements. COD remittance and freight invoicing are not in the API surface: ClickPost does not take money for the carrier, the brand's own carrier contracts do.

Writing back: listings, price and stock

Not applicable, this is a carrier aggregator. ClickPost has no catalogue, no price and no stock. The write path is the shipment lifecycle.

Create a shipment and get an AWB

POST https://www.clickpost.in/api/v3/create-order/?username=...&key=... for India, POST .../api/v4/create-order/ for international. The request body is four objects: pickup_info, drop_info, shipment_details and an optional additional. shipment_details.courier_partner carries the ClickPost courier partner id, delivery_type is FORWARD or RVP, order_type is COD or prepaid, and items[] carries sku, price, weight, quantity and HS code.

{
  "meta": {
    "status": 200,
    "message": "Order Placed Successfully",
    "success": true,
    "username": "test-user",
    "reference_number": "TEST-20230428"
  },
  "result": {
    "label": "https://clickpost-shipping-label.s3.amazonaws.com:443/ECOM/TEST-20230428.pdf",
    "waybill": "4600001ASDF",
    "order_id": "TEST-Order-ID",
    "sort_code": "MH/WHH/BMF",
    "account_code": "EcomExpress Forward",
    "courier_name": "EcomExpress",
    "security_key": "2e43f762-0c7c-41ef-ges5-20a3cc7aascw",
    "reference_number": "TEST-20230428",
    "courier_partner_id": 3,
    "pickup_otp": "1234",
    "delivery_otp": "1234",
    "return_otp": "1234"
  },
  "order_id": 199649298,
  "tracking_id": 6790638236
}

Some carriers are asynchronous. In that case the first call returns meta.status 202, and the same request body is replayed (polling) until the response is 200 or 323 for success, or an error. meta.status 102 means still processing. Setting additional.async to true forces the asynchronous path even on carriers that support synchronous creation. Because polling repeats the same request body, creation must be idempotent on reference_number, and reference_number is the field to keep unique per shipment.

Label, pickup, cancel

GET https://www.clickpost.in/api/v1/fetch/shippinglabel/ with key, waybill and optionally cp_id, to refetch the label for an already manifested order. A label is also returned inline at creation when additional.label is true.
POST https://www.clickpost.in/api/v2/create-pickup/ to raise a pickup request for carriers that need one separately from manifestation.
GET https://www.clickpost.in/api/v1/cancel-order/?key=...&username=...&waybill=...&cp_id=...&account_code=... to cancel, or with reference_number instead of a waybill to terminate a reallocation. Treat meta.status_code 200 or 600 (already cancelled) as cancelled. Status 202 means the carrier accepted the cancellation request but has not confirmed it, which the docs call out specifically for aggregator carriers such as Shiprocket. Anything else means the shipment is still live.

Warning

After a cancellation, several carriers stop updating their tracking API, so the ClickPost dashboard and tracking response can look frozen. Do not infer cancellation from the absence of scans, use the cancellation response code.

Webhooks and notifications

Webhooks are configured from the ClickPost dashboard, not through an API subscription call.

Delivery and verification:

Root level fields include waybill, cp_id, account_code, timestamp, status, the ClickPost normalised status code, and a nested latest_status object mirroring the tracking response.
Verification is a static shared secret in a header, chosen per endpoint: an Authorization: Token bearer value, an x-api-key header, or a webhook-key header. There is no HMAC body signature, so the endpoint must be treated as secret-bearer only and should also validate the AWB against known shipments.
Success is HTTP 200, 201, 202 or 204. The request times out at 5 seconds.
On failure ClickPost retries up to 6 times over 3 hours with linear backoff: 30, 60, 90, 120, 150 and 180 minutes after the initial failure.
Retries replay the same event, so the consumer must deduplicate. The documented dedupe key is waybill plus scan_id, where scan_id is globally unique and monotonically increasing. timestamp plus clickpost_status_code is an equivalent key for a single AWB.
The docs warn that scans can arrive out of logical order and that the schema is extended without notice, so parse permissively and compare timestamps before advancing state.
Webhooks can be retriggered manually from the dashboard.

If webhooks are not configured, poll track-order on the open shipment set. Batching 5 AWBs per call, a 15 to 30 minute cadence is enough for post purchase status, with a tighter loop only on the out for delivery bucket.

Rate limits and pagination

Rate limits are not published. The error code table lists HTTP 429 "Too Many Requests" as a possible server response, which confirms throttling exists but gives no numbers, no quota headers and no burst allowance. Treat the practical limit as a contract question for the onboarding manager.

Pagination models in use:

Tracking: no pagination, up to 5 AWBs per request, same carrier.
Updated orders: time window (start_date, end_date in epoch seconds), advance the window rather than page.
Reporting: asynchronous job, request then poll for status and data.

A workable cadence for a warehouse sync is: webhooks for live status, a 15 minute updated-order delta as a safety net, and a nightly reporting extract for reconciliation.

Mapping to the unified model

Gaps and open questions

The header name for the 24 hour bearer token is only shown as a screenshot. It must be confirmed before building a refresh job.
No published rate limits, quota headers or burst allowance, despite documented 429 responses.
The maximum end_date minus start_date window on the updated order API is stated as capped but the cap value was truncated in the page read.
The NDR action update API is described in prose without a request path or request body schema on the public page.
No sandbox is advertised. Whether test credentials hit real carrier test environments per carrier, or a ClickPost simulator, is unclear.
Shipping cost is absent from the shipment read path. Whether the reporting API exposes billed freight per AWB could not be confirmed from the public field lists.
Some content on the site exists in two places (docs.clickpost.in and docs.clickpost.ai) and the .in copy could not be fetched, so a version skew between the two is possible.
A third party OpenAPI description of ClickPost circulates on GitHub under api-evangelist/clickpost with an unrecorded provenance and empty request schemas. Its paths do not match the first party docs. Do not use it.