Tenant API

v1.0

API for pulling shipment data into external ERP and accounting systems

Overview

The Tenant API provides read-only access to shipment data for integration with external Enterprise Resource Planning (ERP) systems, accounting software, and business intelligence tools. This API is designed for bulk data extraction and reporting purposes.

Access Control

Tenant API tokens are managed by superAdmin users in the Admin Settings page. Contact your system administrator to obtain credentials.

Authentication

All Tenant API requests require Bearer token authentication. Include your API token in the Authorization header:

http

Authorization: Bearer your_tenant_api_token_here

Token Management

Tokens are generated in Admin Settings > Tenant API Credentials
Only one active token exists at a time
Regenerating a token immediately invalidates the previous token
Tokens are 128-byte cryptographic strings

Error Responses

Status	Description
`401 Unauthorized`	Missing, invalid, or revoked API token
`429 Too Many Requests`	Rate limit exceeded (60 requests per 15 seconds)

Base URL

Environment	URL
Production	`https://nbox.now/api/erp`
Staging	`https://staging.nbox.now/api/erp`

Rate Limiting

The Tenant API has dedicated rate limits to ensure system stability:

60 requests per 15-second window
Rate limit headers are included in all responses

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Endpoints

GET

List Shipments

Retrieve a paginated list of shipments within a date range.

GET /api/erp/shipments

Query Parameters

Parameter	Type	Required	Description
`startDate`	String (ISO 8601)	Required	Start date for the query range (e.g., 2024-01-01)
`endDate`	String (ISO 8601)	Required	End date for the query range (e.g., 2024-01-31)
`status`	String	Optional	Filter by shipment status (e.g., delivered, pending)
`page`	Number	Optional	Page number (default: 1)
`limit`	Number	Optional	Results per page (default: 100, max: 500)

Date Range Limit

Maximum date range is 90 days. For larger exports, make multiple requests with consecutive date ranges.

Example Request

bash

curl -X GET "https://nbox.now/api/erp/shipments?startDate=2024-01-01&endDate=2024-01-31&page=1&limit=100" \
  -H "Authorization: Bearer your_tenant_api_token_here"

Success Response (200 OK)

json

{
  "status": "success",
  "data": [
    {
      "id": "clx1abc123...",
      "reference": "ORD-SHOP123-1001",
      "source": "order",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "status": "delivered",
      "paymentStatus": "paid",
      "carrier": "aramex",
      "awb": "123456789",
      "isLocal": true,
      "isReturn": false,
      "shippingRate": 45.00,
      "currency": "QAR",
      "sellerName": "John Smith",
      "sellerCompany": "Acme Store"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1523,
    "totalPages": 16
  },
  "dateRange": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }
}

Response Fields

Field	Type	Description
`id`	String	Unique shipment detail ID
`reference`	String	Human-readable reference number
`source`	String	Source type: order, shipnow, or return
`createdAt`	String (ISO 8601)	Creation timestamp
`status`	String	Current shipment status
`paymentStatus`	String	Payment status for NBox billing
`carrier`	String \| null	Carrier name (e.g., aramex, fedex)
`awb`	String \| null	Airway Bill / tracking number
`isLocal`	Boolean	Whether shipment is domestic
`isReturn`	Boolean	Whether this is a return shipment
`shippingRate`	Number	Actual shipping rate charged
`currency`	String	Currency code (e.g., QAR)
`sellerName`	String \| null	Seller's full name
`sellerCompany`	String \| null	Seller's company name

GET

Get Shipment Detail

Retrieve full details for a specific shipment.

GET /api/erp/shipments/:id

Path Parameters

Parameter	Type	Description
`id`	String	Shipment detail ID (from list endpoint)

Example Request

bash

curl -X GET "https://nbox.now/api/erp/shipments/clx1abc123..." \
  -H "Authorization: Bearer your_tenant_api_token_here"

Success Response (200 OK)

json

{
  "status": "success",
  "data": {
    "id": "clx1abc123...",
    "reference": "ORD-SHOP123-1001",
    "unifiedRefId": "ORD-abc123-REF1001",
    "source": "order",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-16T14:00:00.000Z",
    "status": "delivered",
    "paymentStatus": "paid",

    "carrier": "aramex",
    "awb": "123456789",
    "trackingUrl": "https://www.aramex.com/track/123456789",

    "origin": {
      "address": "123 Warehouse St",
      "city": "Doha",
      "country": "Qatar",
      "countryCode": "QA"
    },
    "destination": {
      "address": "456 Customer Ave",
      "city": "Dubai",
      "country": "United Arab Emirates",
      "countryCode": "AE"
    },

    "customer": {
      "name": "Jane Doe",
      "phone": "+971501234567",
      "email": "jane@example.com"
    },

    "seller": {
      "id": "user_abc123",
      "name": "John Smith",
      "company": "Acme Store",
      "email": "john@acmestore.com"
    },

    "shippingRate": 45.00,
    "displayRate": 50.00,
    "currency": "QAR",
    "codAmount": null,
    "orderSubtotal": 250.00,

    "isLocal": false,
    "isReturn": false,
    "isCOD": false,

    "packageWeight": 2.5,
    "packageLength": 30,
    "packageWidth": 20,
    "packageHeight": 15,
    "boxName": "Medium Box",

    "items": [
      {
        "name": "Product A",
        "quantity": 2,
        "price": 100.00,
        "sku": "PROD-A-001",
        "weight": 0.5
      }
    ]
  }
}

Additional Response Fields (Detail Only)

Field	Type	Description
`unifiedRefId`	String \| null	Unified reference ID for tracking
`updatedAt`	String \| null	Last update timestamp
`trackingUrl`	String \| null	Carrier tracking URL
`origin`	Object	Origin address (address, city, state, country, countryCode, postalCode)
`destination`	Object	Destination address details
`customer`	Object	Customer info (name, phone, email)
`seller`	Object	Seller info (id, name, company, email)
`displayRate`	Number \| null	Rate shown to customer (if different)
`codAmount`	Number \| null	Cash on delivery amount (if COD)
`orderSubtotal`	Number \| null	Order subtotal before shipping
`isCOD`	Boolean	Whether order is Cash on Delivery
`packageWeight`	Number \| null	Package weight in kg
`packageLength/Width/Height`	Number \| null	Package dimensions in cm
`boxName`	String \| null	Selected box name
`items`	Array	Order line items (for orders only)

Error Responses

All error responses follow a consistent format:

json

{
  "status": "failed",
  "message": "Error description here"
}

Status Code	Description
`400 Bad Request`	Invalid parameters (missing dates, invalid format, range exceeds 90 days)
`401 Unauthorized`	Missing, invalid, or revoked API token
`404 Not Found`	Shipment ID not found (detail endpoint only)
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server error

Best Practices

Recommended Patterns

Pagination: Always use pagination for large date ranges. Start with page 1 and iterate until all pages are retrieved.
Date Ranges: For historical exports, break into 90-day chunks and make sequential requests.
Caching: Cache list responses since shipment data for past dates rarely changes.
Error Handling: Implement exponential backoff when receiving 429 rate limit responses.
Token Security: Store your API token securely. Never expose it in client-side code or version control.

Need Help?

For technical support or questions about the Tenant API, contact your system administrator or reach out to NBox technical support.

Email Support Back to Documentation