Developer reference

API Documentation

REST API for shipments, procurement, customs, analytics, and more, multi-tenant, JWT-authenticated, and OpenAPI-aligned.

Base URLhttps://api.quechains.com/api/v1
FormatJSON · UTF-8
AuthBearer JWT

Overview

The QueChains API lets you programmatically manage global supply chain operations for your organization. All resources are scoped by tenant, your JWT includes an organization identifier enforced on every request.

  • Versioned paths under /api/v1/
  • Paginated list endpoints with page, limit, and filters
  • Idempotent writes where noted in endpoint guides
  • Zod-validated request bodies with structured error responses

Authentication

Authenticate with email/password or complete OAuth flows via the web app. Include the access token on every request: 

Authorization: Bearer <access_token>

Access tokens expire in 15 minutes. Use the refresh token at POST /api/v1/auth/refresh to obtain a new pair. Sessions are stored in Redis and can be revoked on logout.

Example: login

curl -X POST https://api.quechains.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"••••••••"}'

Roles

adminFull organization access
operations_managerShipments, carriers, warehouses
logistics_coordinatorCreate and update shipments
customs_agentCustoms declarations and documents
viewerRead-only access
api_userProgrammatic API access

Rate limits

Limits are enforced per user and per organization using Redis:

100
requests / minute / user
1,000
requests / minute / organization

Responses include rate-limit headers. Exceeded limits return 429 Too Many Requests.

Errors

Errors use consistent JSON with an HTTP status code and error object: 

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [ … ]
  }
}
StatusMeaning
400Validation or malformed request
401Missing or invalid token
403Insufficient role permissions
404Resource not found (or wrong tenant)
429Rate limit exceeded
500Unexpected server error

Authentication

Register users, obtain tokens, manage profile and MFA.

POST/api/v1/auth/registerCreate account & organization
POST/api/v1/auth/loginObtain access and refresh tokens
POST/api/v1/auth/refreshRefresh access token
POST/api/v1/auth/logoutInvalidate session
GET/api/v1/auth/profileGet current user profile
PATCH/api/v1/auth/profileUpdate profile
POST/api/v1/auth/change-passwordChange password
POST/api/v1/auth/mfa/setupBegin MFA setup
POST/api/v1/auth/mfa/verifyVerify and enable MFA
POST/api/v1/auth/mfa/disableDisable MFA

Shipments

Create and track multi-modal shipments, events, documents, and alerts.

Example: create shipment

curl -X POST https://api.quechains.com/api/v1/shipments \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin": { "city": "Shanghai", "country": "CN" },
    "destination": { "city": "Los Angeles", "country": "US" },
    "mode": "sea",
    "incoterms": "FOB"
  }'
GET/api/v1/shipmentsList shipments (paginated, filterable)
POST/api/v1/shipmentsCreate shipment
GET/api/v1/shipments/:idGet shipment by ID
PATCH/api/v1/shipments/:idUpdate shipment
DELETE/api/v1/shipments/:idDelete shipment
GET/api/v1/shipments/statsShipment statistics
POST/api/v1/shipments/:id/eventsAdd tracking event
POST/api/v1/shipments/:id/documentsUpload document
PATCH/api/v1/shipments/:id/alerts/:alertId/acknowledgeAcknowledge alert

Purchase orders

Procurement lines linked to suppliers and downstream logistics.

GET/api/v1/purchase-ordersList purchase orders
POST/api/v1/purchase-ordersCreate purchase order
GET/api/v1/purchase-orders/:idGet purchase order
PATCH/api/v1/purchase-orders/:idUpdate purchase order
DELETE/api/v1/purchase-orders/:idDelete purchase order
POST/api/v1/purchase-orders/:id/approveApprove purchase order

Carriers

Carrier master data, performance scores, and rate cards.

GET/api/v1/carriersList carriers
POST/api/v1/carriersCreate carrier
GET/api/v1/carriers/:idGet carrier
PATCH/api/v1/carriers/:idUpdate carrier
DELETE/api/v1/carriers/:idDelete carrier
PATCH/api/v1/carriers/:id/performanceUpdate performance metrics
GET/api/v1/carriers/:id/rate-cardsList rate cards
POST/api/v1/carriers/:id/rate-cardsCreate rate card

Warehouses

Warehouse locations and inventory positions.

GET/api/v1/warehousesList warehouses
POST/api/v1/warehousesCreate warehouse
GET/api/v1/warehouses/:idGet warehouse
PATCH/api/v1/warehouses/:idUpdate warehouse
DELETE/api/v1/warehouses/:idDelete warehouse
GET/api/v1/warehouses/:id/inventoryList inventory
POST/api/v1/warehouses/:id/inventoryAdd inventory item
PATCH/api/v1/warehouses/:id/inventory/:itemIdUpdate inventory item
DELETE/api/v1/warehouses/:id/inventory/:itemIdRemove inventory item

Suppliers

Supplier onboarding, approval, and performance tracking.

GET/api/v1/suppliersList suppliers
POST/api/v1/suppliersCreate supplier
GET/api/v1/suppliers/:idGet supplier
PATCH/api/v1/suppliers/:idUpdate supplier
DELETE/api/v1/suppliers/:idDelete supplier
POST/api/v1/suppliers/:id/approveApprove supplier
PATCH/api/v1/suppliers/:id/performanceUpdate performance

Customs

Declarations, HS lookup, submission, and clearance.

GET/api/v1/customsList declarations
POST/api/v1/customsCreate declaration
GET/api/v1/customs/:idGet declaration
PATCH/api/v1/customs/:idUpdate declaration
POST/api/v1/customs/:id/submitSubmit for review
POST/api/v1/customs/:id/clearMark as cleared
GET/api/v1/customs/hscode/:codeHS code lookup

Analytics

Dashboards, cost analysis, performance metrics, and reports.

GET/api/v1/analytics/dashboardDashboard summary
GET/api/v1/analytics/shipments/performanceShipment performance
GET/api/v1/analytics/shipments/trendsShipment trends
GET/api/v1/analytics/costs/overviewCost overview
GET/api/v1/analytics/suppliers/performanceSupplier performance
GET/api/v1/analytics/carriers/performanceCarrier performance
GET/api/v1/analytics/carbon-footprintCarbon footprint
POST/api/v1/analytics/reports/generateGenerate report

Disruptions

Risk events, affected shipments, and alternative routes.

GET/api/v1/disruptionsList disruptions
GET/api/v1/disruptions/activeActive disruptions
GET/api/v1/disruptions/:idGet disruption
POST/api/v1/disruptionsCreate disruption
PATCH/api/v1/disruptions/:idUpdate disruption
POST/api/v1/disruptions/:id/resolveResolve disruption
GET/api/v1/disruptions/:id/affected-shipmentsAffected shipments
GET/api/v1/disruptions/:id/alternative-routesAlternative routes

Webhooks

Register HTTPS endpoints to receive signed event payloads when resources change. Configure webhooks in your organization settings or via the integrations workspace.

  • Payloads are JSON with event type, timestamp, and resource snapshot
  • HMAC signature in X-QueChains-Signature header
  • Retry with exponential backoff on non-2xx responses

Event types

shipment.createdshipment.updatedshipment.event.addedcustoms.submittedcustoms.clearedcustoms.helddisruption.detectedpurchase_order.approved

Real-time (WebSocket)

Connect via Socket.IO for live shipment tracking, alerts, and organization notifications. Authenticate with the same JWT used for REST requests. 

wss://api.quechains.com/socket.io/?token=ACCESS_TOKEN

Clients join organization-scoped rooms. Events mirror key webhook types for low-latency dashboards.

Get API access

Sandbox credentials and OpenAPI specs are available for enterprise pilots. Self-serve keys for Growth plans roll out soon.

Request API accessView integrations