canonical: https://jentic.com/apis/ninjavan.co/ninjavan

# Ninja Van API

Jentic publishes the only available OpenAPI specification for Ninja Van API, keeping it validated and agent-ready. Ninja Van is a Southeast Asian last-mile express delivery network covering Singapore, Malaysia, Indonesia, the Philippines, Thailand, and Vietnam. The API is structured around country-scoped paths and provides OAuth 2.0 access tokens, order creation and cancellation, waybill PDF generation, tariff price estimates, PUDO (pick-up and drop-off) Ninja Point listings and partner drop-off triggers, parcel tracking by single tracking number or batch, and webhook receivers for parcel lifecycle events.

## For AI agents

Create and cancel cross-border parcel orders, generate waybills, estimate tariffs, and track parcels on Ninja Van's Southeast Asian delivery network across 11 endpoints under api.ninjavan.co.

## Scope

Does not handle warehousing, fulfilment inventory, or international long-haul outside Southeast Asia - use for Ninja Van last-mile order, waybill, tariff, PUDO, and tracking operations only.

## Capabilities

- Mint an OAuth 2.0 access token through POST /{countryCode}/2.0/oauth/access_token
- Create a parcel delivery order through POST /{countryCode}/4.1/orders
- Generate a waybill PDF for a created order through GET /{countryCode}/2.0/reports/waybill
- Cancel an order before pickup through DELETE /{countryCode}/2.2/orders/{trackingNo}
- Estimate delivery tariffs before booking through POST /{countryCode}/1.0/public/price
- Look up Ninja Point pick-up and drop-off locations through GET /{countryCode}/2.0/pudos
- Track parcels singly or in batches through /{countryCode}/1.0/orders/tracking-events

## Use cases

### E-commerce checkout shipping integration

Online stores selling across Southeast Asia can quote shipping at checkout and create the parcel order at order confirmation. POST /{countryCode}/1.0/public/price returns a tariff estimate; POST /{countryCode}/4.1/orders creates the order and returns a tracking number; GET /{countryCode}/2.0/reports/waybill returns the printable label. The country code in each path keeps SG, MY, ID, PH, TH, and VN orders cleanly separated.

Example prompt: POST an order to `/sg/4.1/orders` with sender, recipient, and parcel dimensions, then call `/sg/2.0/reports/waybill`?trackingNo=... to retrieve the label PDF.

### Shipping cost estimation

Marketplaces and 3PLs can show buyers a live shipping price before checkout completes. POST /{countryCode}/1.0/public/price accepts origin and destination, weight, and dimensions, and returns the Ninja Van tariff. The endpoint is rate-limited to 20 calls per minute, so callers should cache by route.

Example prompt: POST a tariff request to `/vn/1.0/public/price` with origin postcode, destination postcode, and 2kg weight; cache the returned price for 10 minutes.

### Parcel tracking dashboards

Operations teams need an internal dashboard showing the status of every in-flight parcel. GET /{countryCode}/1.0/orders/tracking-events accepts a list of tracking numbers and returns the latest events for each, while the single-parcel variant returns full event history for one tracking number. Webhooks should be the primary update channel; the GET endpoints are for reconciliation when webhooks fail.

Example prompt: Call GET `/my/1.0/orders/tracking-events` with tracking_numbers=NV001,NV002,NV003 and write the latest status for each into the operations dashboard.

### AI agent shipping operations

An AI agent embedded in a customer-support workflow can look up parcel status, cancel mistakenly created orders, and quote replacement shipping costs without the operator opening the carrier portal. Through Jentic, the agent searches by intent and Jentic returns the right Ninja Van endpoint with its schema. The OAuth client credentials are held in the vault and never enter the agent's chat context.

Example prompt: Search Jentic for 'cancel a Ninja Van order', load DELETE /{countryCode}/2.2/orders/{trackingNo}, and execute it for trackingNo NVSG12345.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/{countryCode}/2.0/oauth/access_token` | Mint an OAuth 2.0 access token |
| POST | `/{countryCode}/4.1/orders` | Create a parcel delivery order |
| DELETE | `/{countryCode}/2.2/orders/{trackingNo}` | Cancel an order before pickup |
| GET | `/{countryCode}/2.0/reports/waybill` | Generate a waybill PDF |
| POST | `/{countryCode}/1.0/public/price` | Estimate delivery tariff |
| GET | `/{countryCode}/1.0/orders/tracking-events/{trackingNumber}` | Get tracking events for a single parcel |
| GET | `/{countryCode}/1.0/orders/tracking-events` | Get tracking events for a batch of parcels |
| GET | `/{countryCode}/2.0/pudos` | List Ninja Points in a country |

## Key resources

- **OAuth API** — Mint and refresh access tokens for sandbox and production
- **Order API** — Create, cancel, and waybill orders
- **Tariff API** — Estimate delivery price for a route and parcel
- **PUDO API** — List Ninja Points and trigger partner drop-off scans
- **Tracking API** — Retrieve tracking events for one or many parcels
- **Webhooks** — Receive parcel lifecycle event callbacks

## Why Jentic

- **Setup:** Wiring Ninja Van by hand means running its OAuth2 access-token exchange, choosing the sandbox or production host, and threading the country code into every path yourself. Through Jentic you install once, import the Ninja Van API from the API Directory, store the client credentials once, and your agent calls it.
- **Permission scoping:** Ninja Van carries the tracking number in the URL path (/{countryCode}/2.2/orders/{trackingNo}), so a rule can pin your agent to one order: it can read tracking events for that order and nothing else. You choose the operations it may call, so destructive ones like cancelling an order are not included unless you add them.
- **Credential handling:** Your Ninja Van client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a delivery order' or 'track a parcel by tracking number', and Jentic returns the matching Ninja Van operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **FedEx API** — FedEx provides global express shipping, including international legs into and out of Southeast Asia.
- **DHL Shipment Tracking API** — DHL's tracking API can be polled alongside Ninja Van for multi-leg international shipments.
- **HubSpot CRM Orders API** — HubSpot Orders track the commercial side of each shipment that Ninja Van delivers.

## FAQ

### Why is there no official OpenAPI spec for Ninja Van API?

Ninja Van publishes API documentation but does not ship a maintained OpenAPI specification for direct download. Jentic generates and maintains this spec so that AI agents and developers can call Ninja Van API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Ninja Van API use?

Ninja Van uses OAuth 2.0 with client credentials issued from the Ninja Dashboard. Call POST /{countryCode}/2.0/oauth/access_token to mint a bearer token, then send it as Authorization: Bearer <token> on every other call. Through Jentic, the client ID and key are held in the vault and the bearer token is refreshed server-side.

### Can I cancel an order through the API?

Yes. DELETE /{countryCode}/2.2/orders/{trackingNo} cancels the order before pickup. Note this endpoint targets v2.2 even though order creation is on v4.1 - the spec preserves the version that each operation runs on.

### What are the rate limits for the Ninja Van API?

Several endpoints are rate-limited. The tariff estimate endpoint /{countryCode}/1.0/public/price is capped at 20 calls per minute. The OAuth token, waybill, and tracking-events endpoints are also rate-limited; expect HTTP 429 with a retry-after if exceeded.

### How do I create a Ninja Van order through Jentic?

Run pip install jentic, search Jentic for 'create a Ninja Van parcel order', and load POST /{countryCode}/4.1/orders. Provide sender and recipient blocks, parcel dimensions, and the country code (sg, my, id, ph, th, vn). Jentic mints and attaches the OAuth bearer token.

### Does the Ninja Van API support all six Southeast Asian markets?

Yes. The country code is part of the path (for example /sg, /my, /id, /ph, /th, /vn), and each market has its own developer support contact email. Production access is granted per market after an integration audit.

### Can I limit what my agent is allowed to do with the Ninja Van API?

Yes. Because Jentic One is self-hosted, your own rules decide which Ninja Van operations and credentials your agent may use. You pick the operations it can call, so a read-only tracking agent gets GET /{countryCode}/1.0/orders/tracking-events while destructive operations like DELETE /{countryCode}/2.2/orders/{trackingNo} stay off unless you add them. Since the tracking number sits in the URL path, a rule can pin the agent to a single order so it reads events for that order and nothing else.