Developer Docs · v1

Kooryr API Reference

Connect your store to Kooryr to generate shipping orders, compare rates, and track shipments. This guide covers everything you need to ship your first order via the API.

Overview

Base URL

https://api.kooryr.com

• All requests and responses use application/json
• Authentication is required on all endpoints except GET /rates/slabs
• The API is currently scoped to India domestic shipping

Authentication

Kooryr uses session-based JWT authentication. Register an account, verify your email, then log in to receive a token. Pass this token as a Bearer header on all subsequent requests.

1. Register

POST/auth/register

namerequired

string

Your full name or store name.

emailrequired

string

Email address — used for login and notifications.

passwordrequired

string

Minimum 8 characters.

user_type

string

store (default) or logistics. Use store for e-commerce integrations.

Request

curl -X POST https://api.kooryr.com/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Store",
    "email": "ops@acme.in",
    "password": "securepass123",
    "user_type": "store"
  }'

Response · 201

{
  "message": "Account created. Please check your email to verify your account.",
  "user": {
    "id": "a1b2c3d4-...",
    "name": "Acme Store",
    "email": "ops@acme.in",
    "user_type": "store"
  }
}

A verification link is sent to your email. You must verify before you can log in.

2. Log in

POST/auth/login

Request

curl -X POST https://api.kooryr.com/auth/login \
  -H "Content-Type: application/json" \
  -c cookies.txt \
  -d '{
    "email": "ops@acme.in",
    "password": "securepass123"
  }'

Response · 200

{
  "user": {
    "id": "a1b2c3d4-...",
    "name": "Acme Store",
    "email": "ops@acme.in",
    "user_type": "store",
    "onboarding_complete": false
  }
}

The response sets an httpOnly cookie named token containing a signed JWT (valid 7 days). For server-side integrations, capture this cookie and replay it on subsequent requests.

Using the token as a Bearer header (server-to-server)

# Extract the JWT from the Set-Cookie header after login, then:
curl https://api.kooryr.com/orders \
  -H "Authorization: Bearer <your_jwt_token>"

Zone Reference

Every order requires a zone. Kooryr determines zone automatically from the origin and destination pincodes in the dashboard, but if you are integrating via the API you must supply it. Use the table below, or call GET /rates/slabs for machine-readable rate data.

Zone	Description	Examples
local	Same sorting district (first 3 pincode digits match) or within the same metro city	Andheri → Bandra, Delhi → Delhi
metro	Between two of the top 8 metro cities	Mumbai → Bangalore, Delhi → Pune
regional	Different districts but same state/postal circle	Jaipur → Jodhpur, Lucknow → Agra
national	Different states	Mumbai → Hyderabad, Delhi → Chennai
remote	J&K, North-East states, A&N Islands, Lakshadweep, Sikkim	Srinagar, Shillong, Port Blair

Unsure of the zone? Use the rate calculator in your dashboard or POST /rates/calculate which also returns the computed zone.

Rate Calculation

Calculate the shipping cost for a given zone and weight before creating an order.

Calculate rate

POST/rates/calculate· requires auth

zonerequired

string

One of local · regional · metro · national · remote

weight_kgrequired

number

Shipment weight in kilograms. e.g. 1.5

payment_type

string

prepaid (default) or cod. COD rates are ~15% higher.

Request

curl -X POST https://api.kooryr.com/rates/calculate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "zone": "national",
    "weight_kg": 1.5,
    "payment_type": "prepaid"
  }'

Response · 200

{
  "zone": "national",
  "weight_kg": 1.5,
  "payment_type": "prepaid",
  "base": 35,
  "add05": 44,
  "add1": 0,
  "total": 79
}

Pricing is in INR. base covers the first 0.5 kg.add05 is additional charge for each 0.5 kg up to 5 kg.add1 covers each 1 kg above 5 kg.

Get rate slabs (public)

GET/rates/slabs· no auth required

Returns the full prepaid and COD rate slabs for all zones.

Request

curl https://api.kooryr.com/rates/slabs

Creating an Order

An order is a shipment manifest — it records the origin, destination, weight, and cost for a parcel. Once created, the order can be assigned to a carrier to generate a shipping label.

Create order

POST/orders· requires auth

origin_pincoderequired

string

6-digit India pincode of the pickup location.

destination_pincoderequired

string

6-digit India pincode of the delivery address.

zonerequired

string

Shipping zone — see Zone Reference.

weight_kgrequired

number

Shipment weight in kg.

estimated_cost

number

Pre-calculated shipping cost in INR. Use the /rates/calculate endpoint to get this value.

payment_type

string

prepaid (default) or cod.

Request

curl -X POST https://api.kooryr.com/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "origin_pincode": "400001",
    "destination_pincode": "110001",
    "zone": "national",
    "weight_kg": 1.5,
    "estimated_cost": 79,
    "payment_type": "prepaid"
  }'

Response · 201

{
  "order": {
    "id": "f7e8d9c0-...",
    "user_id": "a1b2c3d4-...",
    "origin_pincode": "400001",
    "destination_pincode": "110001",
    "zone": "national",
    "weight_kg": "1.50",
    "estimated_cost": "79.00",
    "payment_type": "prepaid",
    "status": "pending",
    "carrier": null,
    "tracking_id": null,
    "created_at": "2026-03-26T09:00:00.000Z"
  }
}

Typical integration flow

Determine the zone from the customer's pincode (see zone table)
Call POST /rates/calculate to get estimated_cost
Call POST /orders with all fields to create the order
Use the returned order.id to purchase a carrier label via POST /carriers/amazon/rates

Listing Orders

List your orders

GET/orders· requires auth

Returns the 50 most recent orders for the authenticated account, newest first.

Request

curl https://api.kooryr.com/orders \
  -H "Authorization: Bearer <token>"

Response · 200

{
  "orders": [
    {
      "id": "f7e8d9c0-...",
      "origin_pincode": "400001",
      "destination_pincode": "110001",
      "zone": "national",
      "weight_kg": "1.50",
      "estimated_cost": "79.00",
      "payment_type": "prepaid",
      "status": "pending",
      "carrier": null,
      "tracking_id": null,
      "created_at": "2026-03-26T09:00:00.000Z"
    }
  ]
}

Errors

All errors return a JSON object with an error field describing the problem.

Status	Meaning
400	Bad Request — a required field is missing or invalid.
401	Unauthorised — missing or expired token.
403	Forbidden — email not yet verified.
404	Not Found — the requested resource does not exist.
409	Conflict — e.g. email already registered.
500	Server Error — something went wrong on our end.

Error shape

{ "error": "origin_pincode, destination_pincode, zone, weight_kg are required" }

More endpoints (carrier labels, tracking, webhooks) are being added. Contact us if you need help integrating.