Retrieve tracking events for a single parcel (GET /{countryCode}/1.0/orders/tracking-events/{trackingNumber}) or for a list of parcels (GET /{countryCode}/1.0/orders/tracking-events). Ninja Van positions webhooks as the primary push mechanism for status changes.
openapi: 3.0.3
info:
title: Ninja Van API (ninjaAPI)
description: >-
ninjaAPI is Ninja Van's REST API for integrating last-mile logistics across
Southeast Asia (Singapore, Malaysia, Indonesia, Philippines, Vietnam,
Thailand). Merchants create and cancel delivery orders, generate waybills
(AWB), estimate tariffs, look up Ninja Point (PUDO) locations, and pull
tracking events; Ninja Van pushes order status changes back to merchants via
webhooks. Every request is country-scoped - the country code is the first
path segment (for example /SG/, /MY/, /ID/) - and authenticated with an
OAuth2 client-credentials bearer token. Production access is granted per
merchant after an integration audit; the sandbox only supports the Singapore
(sg) country code.
Paths, methods, and versions in this document are grounded in Ninja Van's
published OpenAPI specification (v4.1.0). Request/response schemas are
modeled from the documentation and are simplified; verify exact field lists
against the live API reference before production use.
version: '4.1.0'
contact:
name: Ninja Van Developer Support
url: https://api-docs.ninjavan.co/
servers:
- url: https://api.ninjavan.co/{countryCode}
description: Production (countryCode is one of sg, my, id, ph, vn, th)
variables:
countryCode:
default: sg
enum:
- sg
- my
- id
- ph
- vn
- th
- url: https://api-sandbox.ninjavan.co/{countryCode}
description: Sandbox (only the sg country code is supported)
variables:
countryCode:
default: sg
enum:
- sg
security:
- bearerAuth: []
tags:
- name: OAuth API
description: OAuth2 client-credentials token issuance.
- name: Order API
description: Create and cancel delivery orders and generate waybills.
- name: Tracking API
description: Pull tracking events for parcels.
- name: Tariff API
description: Estimate shipping price.
- name: PUDO API
description: Ninja Point pick-up / drop-off locations and shipper drop-off.
paths:
/2.0/oauth/access_token:
post:
operationId: requestAccessToken
tags:
- OAuth API
summary: Request access token
description: >-
Exchanges a client ID and client secret for a short-lived OAuth2 access
token using the client-credentials grant. Attach the returned token as a
Bearer token on all subsequent requests.
security: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccessTokenRequest'
responses:
'200':
description: An access token.
content:
application/json:
schema:
$ref: '#/components/schemas/AccessTokenResponse'
'401':
$ref: '#/components/responses/Unauthorized'
/4.2/orders:
post:
operationId: createOrderV42
tags:
- Order API
summary: Create delivery order (v4.2)
description: >-
Creates a delivery order. Version 4.2 of the create-order endpoint. The
request describes the service, the pickup (from) and delivery (to)
parties, and the parcel job (dimensions, delivery instructions, cash on
delivery, delivery timeframe).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderInput'
responses:
'200':
description: The created order, including the assigned tracking number.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/4.1/orders:
post:
operationId: createOrderV41
tags:
- Order API
summary: Create delivery order (v4.1)
description: >-
Creates a delivery order using version 4.1 of the create-order endpoint.
Retained alongside 4.2 for existing integrations.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/OrderInput'
responses:
'200':
description: The created order, including the assigned tracking number.
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/2.2/orders/{trackingNo}:
delete:
operationId: cancelOrder
tags:
- Order API
summary: Cancel order
description: Cancels an order that has not yet been picked up, by its tracking number.
parameters:
- name: trackingNo
in: path
required: true
description: The tracking number of the order to cancel.
schema:
type: string
responses:
'200':
description: Cancellation result.
content:
application/json:
schema:
$ref: '#/components/schemas/CancelResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/2.0/reports/waybill:
get:
operationId: generateWaybill
tags:
- Order API
summary: Generate waybill
description: >-
Generates a waybill (air waybill / shipping label) PDF for one or more
tracking numbers. Access to this endpoint must be granted by Ninja Van
before use.
parameters:
- name: tid
in: query
required: true
description: One or more tracking numbers to include on the waybill.
schema:
type: string
- name: hide_shipper_details
in: query
required: false
description: Whether to hide the shipper's details on the waybill.
schema:
type: boolean
- name: orientation
in: query
required: false
description: Waybill orientation.
schema:
type: string
enum:
- portrait
- landscape
responses:
'200':
description: A waybill document.
content:
application/pdf:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/2.0/reports/international-waybills:
get:
operationId: generateInternationalWaybill
tags:
- Order API
summary: Generate international waybill
description: Generates an international waybill document for cross-border parcels.
parameters:
- name: tid
in: query
required: true
description: One or more tracking numbers to include on the waybill.
schema:
type: string
responses:
'200':
description: An international waybill document.
content:
application/pdf:
schema:
type: string
format: binary
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
/1.0/public/price:
post:
operationId: getPriceEstimate
tags:
- Tariff API
summary: Get price estimate
description: >-
Returns an estimated shipping price for a parcel between an origin and a
destination, based on weight and dimensions.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PriceEstimateInput'
responses:
'200':
description: A price estimate.
content:
application/json:
schema:
$ref: '#/components/schemas/PriceEstimate'
'400':
$ref: '#/components/responses/BadRequest'
/2.0/pudos:
get:
operationId: listNinjaPoints
tags:
- PUDO API
summary: List Ninja Points (PUDO locations)
description: >-
Lists Ninja Point pick-up / drop-off (PUDO) locations and their
capabilities (customer collection, shipper send, returns, and so on).
parameters:
- name: can_customer_collect
in: query
required: false
schema:
type: boolean
- name: allow_shipper_send
in: query
required: false
schema:
type: boolean
- name: allow_customer_return
in: query
required: false
schema:
type: boolean
responses:
'200':
description: A list of Ninja Point locations.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PudoLocation'
'401':
$ref: '#/components/responses/Unauthorized'
/1.0/send-orders/drop-off:
post:
operationId: triggerShipperDropOff
tags:
- PUDO API
summary: Trigger shipper drop-off for parcel
description: Triggers the shipper drop-off flow for a parcel at a Ninja Point.
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
'200':
description: Drop-off acknowledgement.
content:
application/json:
schema:
type: object
additionalProperties: true
'401':
$ref: '#/components/responses/Unauthorized'
/1.0/send-orders/{trackingId}:
get:
operationId: scanParcelForDropOff
tags:
- PUDO API
summary: Scan parcel for shipper drop-off
description: Scans a parcel by tracking ID as part of the shipper drop-off flow.
parameters:
- name: trackingId
in: path
required: true
schema:
type: string
responses:
'200':
description: Scan result.
content:
application/json:
schema:
type: object
additionalProperties: true
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/1.0/orders/tracking-events/{trackingNumber}:
get:
operationId: getTrackingEventsForParcel
tags:
- Tracking API
summary: Get events for single parcel
description: Returns the tracking events recorded for a single parcel.
parameters:
- name: trackingNumber
in: path
required: true
schema:
type: string
responses:
'200':
description: Tracking events for the parcel.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TrackingEvent'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/1.0/orders/tracking-events:
get:
operationId: getTrackingEventsForParcels
tags:
- Tracking API
summary: Get events for list of parcels
description: Returns tracking events for a list of parcels.
parameters:
- name: tracking_number
in: query
required: true
description: Comma-separated or repeated tracking numbers.
schema:
type: string
responses:
'200':
description: Tracking events for the requested parcels.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/TrackingEvent'
'401':
$ref: '#/components/responses/Unauthorized'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
OAuth2 client-credentials access token obtained from POST
/{countryCode}/2.0/oauth/access_token, passed as
`Authorization: Bearer ACCESS_TOKEN`.
responses:
BadRequest:
description: The request was malformed or failed validation.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Unauthorized:
description: Missing or invalid access token.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: >-
The caller lacks permission - wrong environment/country code, integration
audit not passed, waybill access not granted, or a frozen account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Error:
type: object
properties:
error:
type: object
properties:
title:
type: string
message:
type: string
details:
type: object
additionalProperties: true
AccessTokenRequest:
type: object
required:
- client_id
- client_secret
- grant_type
properties:
client_id:
type: string
client_secret:
type: string
grant_type:
type: string
enum:
- client_credentials
default: client_credentials
AccessTokenResponse:
type: object
properties:
access_token:
type: string
token_type:
type: string
example: bearer
expires:
type: integer
description: Expiry as a Unix timestamp.
expires_in:
type: integer
description: Lifetime of the token in seconds.
Contact:
type: object
description: A pickup or delivery party.
properties:
name:
type: string
phone_number:
type: string
email:
type: string
address:
type: object
properties:
address1:
type: string
address2:
type: string
area:
type: string
city:
type: string
state:
type: string
address_type:
type: string
country:
type: string
postcode:
type: string
ParcelJob:
type: object
description: Details of the parcel and how it should be handled.
properties:
is_pickup_required:
type: boolean
pickup_service_type:
type: string
pickup_date:
type: string
format: date
delivery_start_date:
type: string
format: date
delivery_timeslot:
type: object
additionalProperties: true
dimensions:
type: object
properties:
weight:
type: number
length:
type: number
width:
type: number
height:
type: number
cash_on_delivery:
type: number
allow_weekend_delivery:
type: boolean
OrderInput:
type: object
required:
- service_type
- from
- to
- parcel_job
properties:
service_type:
type: string
description: For example Parcel.
service_level:
type: string
description: For example Standard.
requested_tracking_number:
type: string
reference:
type: object
properties:
merchant_order_number:
type: string
from:
$ref: '#/components/schemas/Contact'
to:
$ref: '#/components/schemas/Contact'
parcel_job:
$ref: '#/components/schemas/ParcelJob'
marketplace:
type: object
additionalProperties: true
Order:
allOf:
- $ref: '#/components/schemas/OrderInput'
- type: object
properties:
tracking_number:
type: string
status:
type: string
created_at:
type: string
format: date-time
CancelResponse:
type: object
properties:
tracking_number:
type: string
status:
type: string
PriceEstimateInput:
type: object
properties:
service_type:
type: string
service_level:
type: string
from:
$ref: '#/components/schemas/Contact'
to:
$ref: '#/components/schemas/Contact'
weight:
type: number
dimensions:
type: object
properties:
length:
type: number
width:
type: number
height:
type: number
PriceEstimate:
type: object
properties:
currency:
type: string
price:
type: number
breakdown:
type: object
additionalProperties: true
PudoLocation:
type: object
properties:
id:
type: string
name:
type: string
address:
type: string
latitude:
type: number
longitude:
type: number
can_customer_collect:
type: boolean
allow_shipper_send:
type: boolean
TrackingEvent:
type: object
properties:
tracking_number:
type: string
status:
type: string
timestamp:
type: string
format: date-time
description:
type: string