Developer API·REST API & Webhooks

Integrate SellerPadi Dispatches & Receipts

Programmatically create tamper-proof dispatches, generate dual-layer QR stickers, verify PIN handovers, and stream real-time logistics webhooks directly into your ERP or e-commerce store.

Getting Started Guide API Reference View Quota Tiers

Getting Started: From Sign-Up to First Dispatch

Follow these 5 steps to go from zero to a fully automated package tracking integration.

Create a Merchant Account

Sign up on SellerPadi using Google or Email or Phone. During profile setup, select your merchant business type to unlock the shipments and smart receipts workspace.

Generate Your Secret API Key

Open your Settings page and scroll to the Developer REST API section. Click "Generate API Key" to create a secret key in the format rst_live_.... Copy this key securely — it authenticates all your server-to-server API calls.

Go to Settings →

Register Your First Dispatch

Call POST /api/v1/shipments/create with your API key in the Authorization header. The response returns a unique packageId, consumer trackingCode, SP-prefixed handover secret (innerSecret), and shipment record.

See Code Example ↓

Print & Affix API-Generated QR Sticker

Every shipment creation call automatically returns ready-to-print qrImageUrl and scanUrl links, plus a dedicated GET /api/v1/shipments/[id]/qr endpoint for SVG/PNG label printing onto boxes or poly-mailers.

Complete Delivery with PIN Handover

At delivery, the recipient provides their secret scratch-off PIN. The recipient or rider enters it on the scan page (or your backend calls POST /api/v1/shipments/[id]/verify). On match, the package status updates to Verified and your webhook fires.

Authentication

All authenticated endpoints require your secret API key. You can pass it in one of two ways:

Option 1: Authorization Header (Recommended)Authorization: Bearer rst_live_8f921a4b901e23f...

Option 2: Custom Headerx-api-key: rst_live_8f921a4b901e23f...

Security Notice: Never expose your API key in client-side browser code. Only use it in server-to-server calls from your backend (Node.js, Python, PHP, etc.). If your key is compromised, roll it immediately from Settings.

Sandbox Testing Console

Interactive REST API Playground

Test making live requests with your API key (`rst_test_...` or `rst_live_...`) directly in your browser.

Manage API Keys in Settings →

Enter Your API Key (Authorization Bearer Header):Generate Key in Settings →

Tip: Use a Test Sandbox Key (`rst_test_...`) to simulate requests safely without consuming live dispatch quota.

Select Endpoint to Test:

Request JSON Body:

API Response Output:

Click "Execute API Request" above to test this endpoint live and inspect response output.

API Request Code Examples:

REST API Endpoint Reference

Base URL: https://sellerpadi.com/api/v1

POST/shipments/create

API Key Required

Registers a new commercial shipment, reserves your monthly quota, writes a tamper-proof record to the blockchain ledger, and returns a unique packageId, trackingCode, SP-prefixed handover secret (innerSecret), and shipment object.

curl -X POST https://app-SellerPadi.vercel.app/api/v1/shipments/create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rst_live_8f921a4b901e23f..." \
  -d '{
    "packageName": "iPhone 15 Pro Dispatch",
    "weight": "0.45",
    "receiverPhone": "+2348012345678"
  }'

Request Body Parameters:

• packageName (string, required): Reference title
• receiverName (string, optional): Recipient full name
• receiverPhone (string, required): Recipient phone number
• destination (string, optional): Destination city / area
• weight (string, optional): Weight in kg
• metadata (object, optional): Custom key-value data

200 OK Response:

• success: true
• packageId: "0x4a91b2..." (internal package ID)
• trackingCode: "SHPT-4A91B2C3E8F0" (consumer tracking code)
• scanUrl: "https://sellerpadi.com/scan/SHPT-4A91B2C3E8F0"
• qrImageUrl: "https://api.qrserver.com/..." (ready-to-print PNG link)
• qrApiUrl: "https://sellerpadi.com/api/v1/shipments/SHPT-4A91B2C3E8F0/qr"
• innerSecret: "SP-A8F2B1C0" (8-char handover secret)
• shipment: Full Shipment Object

GET/shipments

API Key Required

Returns all shipments belonging to your merchant account, sorted by most recent first. Useful for syncing your order management system or building custom dashboards.

curl -X GET "https://app-SellerPadi.vercel.app/api/v1/shipments" \
  -H "Authorization: Bearer rst_live_8f921a4b901e23f..."

GET/shipments/[id]/verify

Public · No Auth Required

Public endpoint for QR scan verification. Returns package weight, carrier info, current status (InTransit, Delivered, Disputed), and chain-of-custody timeline. This is the same endpoint called when anyone scans a physical QR sticker.

curl -X GET "https://app-SellerPadi.vercel.app/api/v1/shipments/SHPT-8F912A3B4C5D/verify"

POST/shipments/[id]/handover

API Key Required

Transfers package custody to a dispatch rider, driver, or warehouse handler. Updates status to "InTransit", logs an on-chain event, and fires a shipment.handover webhook callback.

curl -X POST "https://app-SellerPadi.vercel.app/api/v1/shipments/SHPT-8F912A3B4C5D/handover" \
  -H "Authorization: Bearer rst_live_8f921a4b901e23f..." \
  -H "Content-Type: application/json" \
  -d '{ "riderName": "John Rider", "riderPhone": "+2348011223344", "location": "Ikeja Hub, Lagos" }'

POST/shipments/[id]/verify

PIN Verification

Verifies the 8-character Secret Handover PIN at physical delivery. On a match, status updates to "Verified" and a shipment.delivered webhook callback fires with company details.

curl -X POST "https://app-SellerPadi.vercel.app/api/v1/shipments/SHPT-8F912A3B4C5D/verify" \
  -H "Authorization: Bearer rst_live_8f921a4b901e23f..." \
  -H "Content-Type: application/json" \
  -d '{ "innerSecret": "SP-A8F2B1C0", "location": "Lekki, Lagos" }'

GET/shipments/[id]/history

Public Timeline

Fetches the complete custody event timeline (Created, InTransit, Handover, Verified, Disputed) for a package. Passing an authorized rider PIN unlocks rider contact details.

curl -X GET "https://app-SellerPadi.vercel.app/api/v1/shipments/SHPT-8F912A3B4C5D/history"

POST/shipments/[id]/dispute

API Key Required

Files a formal delivery dispute for damaged, stolen, or missing contents. Requires the package to be in "InTransit" status(i.e. handed over for delivery). Updates package status to "Disputed", records an on-chain event, and triggers a shipment.disputed webhook.

curl -X POST "https://app-SellerPadi.vercel.app/api/v1/shipments/SHPT-8F912A3B4C5D/dispute" \
  -H "Authorization: Bearer rst_live_8f921a4b901e23f..." \
  -H "Content-Type: application/json" \
  -d '{ "innerSecret": "SP-A8F2B1C0", "reason": "Damaged contents on arrival", "location": "Lagos" }'

PATCH/shipments/[id]

API Key Required

Updates package metadata (name, receiver name, receiver phone, destination, weight). Only the package creator can edit details. Cannot modify packages in "Verified" or "Disputed" status. receiverPhone cannot be set to empty.

curl -X PATCH "https://app-SellerPadi.vercel.app/api/v1/shipments/SHPT-8F912A3B4C5D" \
  -H "Authorization: Bearer rst_live_8f921a4b901e23f..." \
  -H "Content-Type: application/json" \
  -d '{ "packageName": "Updated Parcel Name", "receiverPhone": "+2348099887766", "destination": "Lekki Phase 1" }'

GET/shipments/[id]/qr

Public QR Generator

Generates a QR code image or returns JSON metadata containing direct scan links, ready-to-print PNG/SVG URLs, and caption text for any registered package or item. Supports query parameters ?format=json|png|svg and ?size=300.

curl -X GET "https://app-SellerPadi.vercel.app/api/v1/shipments/SHPT-8F912A3B4C5D/qr?format=json"

GET/health

Public Health Check

Returns the real-time operational status of the REST API, MongoDB connection, Avalanche Fuji Testnet chain configuration, backend relayer configuration status, and system response latency (in ms).

curl -X GET "https://app-SellerPadi.vercel.app/api/v1/health"

HTTP Status Codes

200Success

201Created

401Invalid API Key

402Quota Exhausted

403Not a Merchant

404Package Not Found

400Bad Request

409State Conflict

429Rate Limited

500Server Error

Real-Time Webhook Subscriptions

Receive instant HTTP POST callbacks when dispatches are created, scanned, delivered, or disputed.

Supported Event Types:

SellerPadi.ping— Connectivity & latency test ping
shipment.created— New package registered via API or Dashboard
shipment.scanned— QR sticker scanned in the field
shipment.handover— Custody transferred to dispatch rider
shipment.delivered— Successful PIN verification & physical delivery
shipment.disputed— Delivery dispute reported for damage / tampering

Configure your target webhook URL once on your Merchant Dashboard or Settings Page. All dispatches created under your merchant profile automatically stream status events to your configured endpoint.

Example Webhook JSON Body:

{
  "event": "shipment.delivered",
  "timestamp": "2026-08-03T14:30:00Z",
  "data": {
    "packageId": "SHPT-8F912A3B4C5D",
    "companyName": "Big Eazi Logistics",
    "shipperAddress": "0x6e799abd05b044acb6d9a59605de21ec845c2180",
    "packageName": "iPhone 15 Pro Dispatch",
    "status": "Verified",
    "recipient": "0x9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b",
    "location": "Lagos, NG",
    "onChainTxHash": "0x8f912a3b4c5d..."
  }
};

Rate Limits & Quota

Free Pilot100operations / month

Starter500operations / month

Growth1,000operations / month

Scale5,000operations / month

When your monthly quota is reached on the Free tier, operations are capped until the billing cycle resets. Paid tiers support uninterrupted operations via transparent universal overage. View all tier details →