Authentication Shipments Tracking Payments Support Admin: Users Admin: Shipments Admin: Stock Admin: Payments Admin: Tickets Admin: Config
⚡ REST API v1.0

ShipFlow API Documentation

Integrate ShipFlow's shipping, tracking, and payment capabilities into your own applications. All endpoints return JSON.

← Back to ShipFlow

📌 Base URL & Authentication

All API requests should be made to the base URL:

https://your-shipflow-domain.com/api

Authentication: Customer endpoints use session-based auth (login → cookie). Admin endpoints require admin session via POST /api/admin/login.

Content-Type: application/json for all POST/PUT requests.

🔐 Authentication

POST/api/signupCreate a new customer account

Request Body

{"name":"John Doe","email":"john@example.com","password":"secret","phone":"+1234567890"}

Response 200

{"user":{"id":"...","name":"John Doe","email":"john@example.com",...}}
POST/api/loginCustomer login

Request Body

{"email":"john@example.com","password":"secret"}

Response 200

{"user":{"id":"...","name":"John Doe",...}}
POST/api/admin/loginAdmin login

Request Body

{"email":"admin@shipflow.com","password":"admin123"}

Response 200

{"admin":{"id":"...","role":"superadmin"}}
GET/api/meGet current logged-in user

Response 200

{"user":{"id":"...","name":"...","email":"...",...}}
PUT/api/settingsUpdate user profile

Request Body

{"name":"John Doe","phone":"+1234567890","country":"USA","address":"123 Main St"}
PUT/api/passwordChange password

Request Body

{"currentPassword":"old","newPassword":"new"}

📦 Shipments

POST/api/shipmentsCreate a new shipment

Request Body

{"origin":"New York","destination":"Los Angeles","weight":2.5,"service":"Express"}

Services

Expressstring1-2 day delivery (highest cost)
Standardstring3-5 day delivery
Economystring5-7 day delivery (lowest cost)

Response 200

{"shipment":{"id":"...","trackingNumber":"SF-XXXXXX","cost":45.00,...}}
GET/api/shipmentsList current user's shipments

Response 200

{"shipments":[{"trackingNumber":"SF-...","status":"Pending",...}]}

📍 Tracking

GET/api/track/{trackingNumber}Get live tracking info with GPS coordinates

Response 200

{"shipment":{"trackingNumber":"SF-...","status":"In Transit","lat":35.0,"lng":-95.0,"origin":"...","destination":"...","history":[...]}}

💳 Payments

POST/api/payments/cryptoSubmit a crypto payment confirmation

Request Body

{"shipmentId":"...","currency":"BTC","txHash":"0x..."}
POST/api/payments/giftcardSubmit a gift card payment

Request Body

{"shipmentId":"...","cardCode":"AMZ-XXXX-XXXX"}
POST/api/payments/request-tagRequest to pay via PayPal/CashApp/Chime tag

Request Body

{"shipmentId":"...","method":"paypal"}

Methods

paypal, cashapp, chime

GET/api/paymentsList current user's payments

💬 Support Tickets

POST/api/ticketsCreate a support ticket

Request Body

{"subject":"Issue with shipment","message":"Details..."}
GET/api/ticketsList user's support tickets
POST/api/tickets/{id}/messagesSend a message in a ticket

Request Body

{"message":"Reply text"}

👤 Admin — Users

GET/api/admin/usersList all users
PUT/api/admin/users/{id}/statusBan or unban a user

Request Body

{"status":"banned"}
DELETE/api/admin/users/{id}Delete a user

📦 Admin — Shipments

GET/api/admin/shipmentsList all shipments
POST/api/admin/shipmentsCreate a shipment (admin)

Request Body

{"origin":"...","destination":"...","weight":2.5,"service":"Express","userId":"..."}
PUT/api/admin/shipments/{id}/statusUpdate shipment status

Request Body

{"status":"In Transit"}

Statuses

Pending, Picked Up, In Transit, Out for Delivery, Delivered

PUT/api/admin/shipments/{id}Edit shipment details

🏷️ Admin — Warehouse Stock

GET/api/admin/stockList all stock items
POST/api/admin/stockAdd a stock item

Request Body

{"name":"Boxes","quantity":100,"price":5.00}
PUT/api/admin/stock/{id}Update a stock item
DELETE/api/admin/stock/{id}Delete a stock item

💰 Admin — Payments

GET/api/admin/paymentsList all payment transactions
POST/api/admin/paymentsCreate a transaction
PUT/api/admin/payments/{id}Update payment status

Request Body

{"status":"confirmed"}

💬 Admin — Support

GET/api/admin/ticketsList all support tickets
POST/api/admin/tickets/{id}/messagesReply to a ticket

⚙️ Admin — Configuration

GET/api/admin/walletsGet crypto wallet addresses
PUT/api/admin/walletsUpdate wallet addresses
GET/api/admin/giftcardsList gift card submissions
GET/api/admin/requestsList payment tag requests
GET/api/admin/statsGet dashboard statistics

Response 200

{"users":150,"activeShipments":42,"delivered":320,"revenue":15420.50,...}

💡 Quick Start Example

// Create a shipment
const res = await fetch('/api/shipments', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    origin: 'New York',
    destination: 'Los Angeles',
    weight: 2.5,
    service: 'Express'
  })
});
const data = await res.json();
console.log(data.shipment.trackingNumber); // "SF-XXXXXX"

// Track it
const track = await fetch('/api/track/' + data.shipment.trackingNumber);
const trackData = await track.json();
console.log(trackData.shipment.status); // "Pending"

ShipFlow API v1.0 · Built with ❤️ for fast shipping

← Back to ShipFlow Home