API reference · https://api.postpin.creatibyte.in/v1

Postpin developer docs

Get from zero to an accurate INR shipping rate in a single call. REST, JSON, India-first — keys, pincodes and zones included.

Quickstart Get API key

Getting started

Quickstart

Send your first POST /rates request. Use your test or live key in the Authorization header — the example below prices Jaipur (302001) → Guwahati (781001).

Grab a key

Create a project and copy your pp_live_… key.

Send pincodes + parcel

POST origin, destination, weight & dimensions.

Receive itemised INR

Get zone, billable weight and a GST breakdown.

POSThttps://api.postpin.creatibyte.in/v1/rates

curl https://api.postpin.creatibyte.in/v1/rates/calculate \
  -H "Authorization: Bearer pp_live_3kQ9xR2pLmZ" \
  -H "Content-Type: application/json" \
  -d '{
  "origin": "302001",
  "destination": "781001",
  "weight": 400,
  "dimensions": { "length": 30, "width": 25, "height": 8, "unit": "cm" },
  "service": "surface",
  "cod": true,
  "declared_value": 1499
}'

Security

Authentication

Postpin uses bearer API keys. Pass your key in the Authorization header on every request. Keep live keys server-side only.

Authorization header

bash

Authorization: Bearer pp_live_3kQ9xR2pLmZ

Key types

pp_test_… runs against the sandbox. pp_live_… bills real usage. Rotate keys anytime from the dashboard.

Allowed domains

Restrict each key to specific domains or IPs. Requests from elsewhere return 403 domain_not_allowed.

Core

Rate API

Calculate an itemised shipping charge between two Indian pincodes. Returns the zone, billable weight (max of actual & volumetric) and a GST-inclusive breakdown.

POSThttps://api.postpin.creatibyte.in/v1/rates

Request parameters

Parameter	Type	Required	Description
origin	string	Required	Pickup pincode (6 digits).
destination	string	Required	Delivery pincode (6 digits).
weight	integer	Required	Actual parcel weight in grams.
dimensions	object	Optional	length, width, height (in cm). Used for volumetric weight = L×W×H/5000.
service	enum	Optional	surface (default), express, or same_day.
cod	boolean	Optional	Set true for cash-on-delivery to add COD handling.
declared_value	integer	Optional	Declared parcel value in INR. Drives the 1.5% COD fee.

Example request body

POST /v1/rates

json

{
  "origin": "302001",
  "destination": "781001",
  "weight": 400,
  "dimensions": { "length": 30, "width": 25, "height": 8, "unit": "cm" },
  "service": "surface",
  "cod": true,
  "declared_value": 1499
}

Example response

200 OK

json

{
  "currency": "INR",
  "zone": "special",
  "zone_label": "Special / Remote",
  "service": "surface",
  "chargeable_weight_g": 1200,
  "volumetric_weight_g": 1200,
  "eta_days": [5, 9],
  "breakdown": [
    { "label": "Base charge",    "amount": 95.00, "hint": "Special / Remote · Surface" },
    { "label": "Weight charge",  "amount": 108.00, "hint": "1.50 kg chargeable" },
    { "label": "Fuel surcharge", "amount": 24.36, "hint": "12%" },
    { "label": "COD handling",   "amount": 57.49, "hint": "₹35 + 1.5%" },
    { "label": "GST",            "amount": 51.27, "hint": "18%" }
  ],
  "total": 336.12,
  "origin":      { "pincode": "302001", "city": "Jaipur",   "state": "Rajasthan" },
  "destination": { "pincode": "781001", "city": "Guwahati", "state": "Assam" },
  "serviceable": true,
  "meta": { "engine_ms": 11, "cached": false, "request_id": "req_7Yh2mKp" }
}

Response schema

Field	Type	Description
currency	string	Always INR.
zone	string	local · regional · metro · national · special.
chargeable_weight_g	integer	max(actual, volumetric) in grams.
volumetric_weight_g	integer	Volumetric weight in grams.
eta_days	[int, int]	Estimated delivery window, low–high.
breakdown	array	Itemised charge lines (label, amount, hint).
total	number	Grand total in INR, GST inclusive.
serviceable	boolean	False when a pincode is unknown or off-network.

Core

Serviceability

Check whether a single pincode is on-network before you quote. Returns city, state, zone, COD availability and an ETA window.

GEThttps://api.postpin.creatibyte.in/v1/serviceability/:pincode

Request

bash

curl https://api.postpin.creatibyte.in/v1/serviceability/781001 \
  -H "Authorization: Bearer pp_live_3kQ9xR2pLmZ"

Response

200 OK

json

{
  "data": {
    "pincode": "781001",
    "serviceable": true,
    "found": true,
    "city": "Guwahati",
    "state": "Assam"
  },
  "meta": { "request_id": "req_7Yh2mKp", "api_version": "v1" }
}

Reference

Pincodes

Search the India Post-synced pincode master by code or city. The master refreshes nightly at 00:30 IST; synced_at tells you the last refresh.

GEThttps://api.postpin.creatibyte.in/v1/pincodes

Request

bash

curl "https://api.postpin.creatibyte.in/v1/pincodes?q=jaipur&limit=5" \
  -H "Authorization: Bearer pp_live_3kQ9xR2pLmZ"

Response

200 OK

json

{
  "data": [
    { "pincode": "302001", "city": "Jaipur", "state": "Rajasthan", "metro": false, "serviceable": true },
    { "pincode": "302002", "city": "Jaipur", "state": "Rajasthan", "metro": false, "serviceable": true }
  ],
  "meta": { "request_id": "req_9Kd4nQw", "api_version": "v1", "has_more": false }
}

Results are paginated with limit (max 100) and a starting_after cursor. The full master covers 19,000+ serviceable pincodes.

Reference

Webhooks

Subscribe to events and Postpin will POST a signed JSON payload to your endpoint. Always verify the Postpin-Signature header before trusting a payload.

Event types

Event	Triggered when
`rate.calculated`	A rate was successfully computed via the API.
`serviceability.checked`	A serviceability lookup was performed.
`sync.completed`	Nightly India Post pincode sync finished.
`sync.failed`	A pincode sync run failed and needs attention.
`subscription.updated`	Plan, status or limits changed for the tenant.
`invoice.paid`	A usage / subscription invoice was paid.

Signed payload

rate.calculated

http

POST /your-endpoint  HTTP/1.1
Postpin-Signature: t=1718900000,v1=5257a869e7ec...
Content-Type: application/json

{
  "id": "evt_2nKp7Yh",
  "type": "rate.calculated",
  "created": 1718900000,
  "livemode": true,
  "data": {
    "request_id": "req_7Yh2mKp",
    "origin": "302001",
    "destination": "781001",
    "zone": "special",
    "total": 336.12,
    "currency": "INR"
  }
}

Verify the signature

verify.js

javascript

import crypto from "node:crypto";

function verify(rawBody, header, secret) {
  const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`)
    .digest("hex");
  // Constant-time compare; reject if t is older than 5 minutes.
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Reference

Errors

Postpin uses conventional HTTP status codes and a stable error envelope: { error: { code, message, request_id } }. Quote the request_id when contacting support.

Status	Code	Meaning
400	`invalid_request`	A required field is missing or malformed.
401	`authentication_failed`	Missing, revoked or invalid API key.
403	`domain_not_allowed`	Request origin is not in the key's allow-list.
404	`pincode_not_found`	Pincode is unknown to the master.
422	`not_serviceable`	Route exists but is not currently serviceable.
429	`rate_limited`	Plan RPM exceeded. Inspect Retry-After.
500	`engine_error`	Unexpected error. Safe to retry with backoff.

429 Too Many Requests

json

{
  "error": {
    "code": "rate_limited",
    "message": "Plan limit of 300 requests/min exceeded.",
    "request_id": "req_7Yh2mKp"
  }
}

Tooling

SDKs

Official, typed SDKs wrap authentication, retries and idempotency. Install your language and you're a few lines from a rate.

Node

bash

npm install @postpin/node

Python

bash

pip install postpin

PHP

bash

composer require postpin/postpin-php

bash

go get github.com/postpin/postpin-go

View on GitHub

Updates

Changelog

Every API change, newest first. The /v1 surface is stable; breaking changes ship behind a new version.

v1.4.012 Jun 2026
- Added GET /v1/serviceability/:pincode for single-call route checks.
- Webhook signatures now include a replay-protection timestamp.
v1.3.028 Apr 2026
- same_day service level is now generally available on metro routes.
- Pincode search endpoint added with fuzzy city matching.
v1.2.003 Mar 2026
- Per-customer rate cards exposed on Growth and above.
- Nightly India Post sync moved to 00:30 IST.

Ready to ship accurate rates?

Create a key in seconds — 1,000 free calls every month.

Get API key Talk to sales