NBOX Now API Documentation
Introduction
The NBOX Now API is designed to seamlessly integrate your e-commerce website with the NBOX Now system, enabling automated shipping rate calculations and order management. Upon integration, users will be able to:
- Retrieve real-time shipping rates from NBOX Now based on product dimensions and shipping destinations.
- Push store information and orders to NBOX Now for streamlined fulfillment and shipping services.
By leveraging this API, merchants can optimize their shipping workflow, reduce manual processing, and ensure efficient order handling.
Base URLs
Use the appropriate base URL depending on your environment:
- Live (Production):
https://nbox.now/api - Staging (Testing):
https://staging.nbox.now/api
Below is a list of the APIs you will use for integrating with NBOX Now. These endpoints allow you to authenticate, manage locations, retrieve shipping rates, and handle orders within the system.
Login API
Log in to the system by calling the authentication endpoint:
A token is returned upon successful authentication and should be used for further API requests.
Method: POST
Endpoint: POST https://{base_url}/login
Request
The following parameters should be included in the request body:
| Name | Type | Required | Description |
|---|---|---|---|
| String | Required | User's email address (e.g., juan.delacruz@email.com) | |
| password | String | Required | User's password (e.g., *******) |
| shopId | String | Required | Shop's unique identifier (domain) (e.g., nbox.now) |
| shopName | String | Required | Shop's name (e.g., Nbox Store) |
| platform | String | Required | E-commerce platform (e.g., WooCommerce, Shopify, Magento, custom) (e.g., woocommerce) |
| url | String | Required | Shop's URL (e.g., https://store.nbox.now) |
| locations | Array of Objects | Optional | optional field and can include shop fulfillment locations. Shop locations (e.g., address: 143 Missing Street, Unknown area, city: Al Rayyan, state: Qatar, countryCode: QA, zip: 0000, country: Qatar) |
Response
| Status | Description |
|---|---|
| 200 OK | Activation successful or failed based on the provided parameters |
| 400 Bad Request | Missing or invalid parameters |
| 401 Unauthorized | Invalid token and/or shop domain |
| 500 Internal Server Error | Server-side error during activation process |
Locations API
To manage locations in the NBOX Now system, you can use the following endpoints. Both endpoints accept the same request body containing an array of location objects.
Make sure to include both the token and the shop domain in the request headers. The API will validate these to ensure the request is coming from an authorized shop. The locations can be provided in a single object or an array of location objects, depending on the platform. The lat and lng fields are optional but can be included if the geographic coordinates of the location are known.
Method: POST
Endpoint:
POST https://{base_url}/locations/add- Add new locations.POST https://{base_url}/locations/update- Update existing locations.
Headers
| Name | Description |
|---|---|
x-nbox-shop-token | The token retrieved from the login API. This token authenticates the user. |
x-nbox-shop-domain | The domain of the e-commerce website (e.g., nbox.now) associated with the shop. |
Request
| Name | Type | Required | Description (with Example) |
|---|---|---|---|
| refId | String | Required | A unique reference ID for the location (e.g., "loc123") |
| refName | String | Required | A unique reference name for displaying the location (e.g., "Main Warehouse") |
| address | String | Required | The street address of the location (e.g., "123 Main St") |
| city | String | Required | The city of the location (e.g., "New York") |
| state | String | Required | The state or province of the location (e.g., "New York") |
| countryCode | String | Required | The two-letter country code (e.g., "US") |
| country | String | Optional | The name of the country (e.g., "United States") |
| zip | String | Required | The ZIP or postal code of the location (e.g., "10001") |
| longitude | Number | Optional | The longitude of the location (e.g., "-73.935242") |
| latitude | Number | Optional | The latitude of the location (e.g., "40.730610") |
Response
| Status | Description |
|---|---|
| 200 OK | Activation successful or failed based on the provided parameters |
| 400 Bad Request | Missing or invalid parameters |
| 401 Unauthorized | Invalid token and/or shop domain |
| 500 Internal Server Error | Server-side error during activation process |
Activation API
Method: POST
Endpoint: POST https://{base_url}/activation
Headers
| Name | Description |
|---|---|
x-nbox-shop-token | The token retrieved from the login API. This token authenticates the user. |
x-nbox-shop-domain | The domain of the e-commerce website (e.g., nbox.now) associated with the shop. |
Request
| Name | Type | Required | Description (with Example) |
|---|---|---|---|
| activate | Boolean | Required | Whether to activate the shop (true or false) (e.g., true) |
| locations | Array | Optional | An array of location objects to be activated (e.g., [{"refId": "loc123", "refName": "Main Warehouse", "address": "123 Main St", "city": "New York", "state": "NY", "zip": "10001", "countryCode": "US", "country": "United States"}]) |
Response
| Status | Description |
|---|---|
| 200 OK | Activation successful or failed based on the provided parameters |
| 400 Bad Request | Missing or invalid parameters |
| 401 Unauthorized | Invalid token and/or shop domain |
| 500 Internal Server Error | Server-side error during activation process |
Rates API
Method: POST
Endpoint: POST https://{base_url}/rates
Headers
| Name | Description |
|---|---|
x-nbox-shop-token | The token retrieved from the login API. This token authenticates the user. |
x-nbox-shop-domain | The domain of the e-commerce website (e.g., nbox.now) associated with the shop. |
Description
This API calculates shipping rates based on product details, origin, and destination. The system intelligently computes dimensions and weight from individual products for accurate rate calculation. Legacy weight/volume parameters are supported for backward compatibility.
Request
Recommended: Use the products array for accurate dimensional weight calculations. The system will compute total weight and volume from individual product specifications.
Main Request Structure
| Name | Type | Required | Description |
|---|---|---|---|
| products | Array | Recommended | List of products with dimensions and weight for accurate calculation |
| volume | Number | Legacy | (Legacy) The volume of the package in cubic units (e.g., 1.5) |
| weight | Number | Legacy | (Legacy) The weight of the package in kilograms (e.g., 2.5) |
| origin | Object | Required | The origin location object (see Origin and Destination Objects below) |
| destination | Object | Required | The destination location object (see Origin and Destination Objects below) |
| type | String | Optional | The type of shipping (e.g., "non_document", "document", etc. Default is "non_document") |
Product Object (Recommended)
| Name | Type | Required | Description |
|---|---|---|---|
| name | String | Required | Name of the product |
| quantity | Number | Required | Quantity of the product |
| price | Number | Required | Price per unit of the product |
| grams | Number | Required | Weight of the product in grams |
| length | Number | Required | Length of the product in cm |
| width | Number | Required | Width of the product in cm |
| height | Number | Required | Height of the product in cm |
| volume | Number | Required | Volume of the product in cubic centimeters (cm³) |
| currency | String | Required | Currency for the product's price |
Origin and Destination Objects
| Name | Type | Required | Description |
|---|---|---|---|
| address | String | Required | Full address, including address lines and any supplementary address info |
| city | String | Required | City |
| state | String | Optional | State or province (accepts null for regions without states) |
| countryCode | String | Required | Country code (e.g., "US", "QA") |
| country | String | Optional | Country Name (e.g., "United States", "Qatar") |
| zip | String | Required | Postal code/Zip code |
| longitude | Number | Optional | Longitude of the address (supports both longitude and lng formats) |
| latitude | Number | Optional | Latitude of the address (supports both latitude and lat formats) |
Response
| Status | Description |
|---|---|
| 200 OK | Activation successful or failed based on the provided parameters |
| 400 Bad Request | Missing or invalid parameters |
| 401 Unauthorized | Invalid token and/or shop domain |
| 500 Internal Server Error | Server-side error during activation process |
Response Body
The response body will contain an array of rate objects, with the following structure:
| Name | Type | Description (with Example) |
|---|---|---|
| id | String | A unique identifier for the rate (e.g., "f9d17f56-7eeb-44ad-bc7e-b95f61d5d2ed") |
| logo | String | URL of the service provider's logo (e.g., "/images/nbox-logistics.png") |
| pickup_dropoff_method | String | The method of pickup and delivery (e.g., "Door to Door") |
| service_name | String | The name of the shipping service (e.g., "NBOX Express Local Delivery") |
| service_code | String | The code for the shipping service (e.g., "NBOX") |
| total_price | Number | The total price for the service in the specified currency (e.g., 20.00) |
| description | String | A description of the service, such as delivery time (e.g., "Estimate Time of Delivery: 3 hours") |
| currency | String | The currency of the total price (e.g., "QAR") |
Order API
Method: POST
Endpoint: POST https://{base_url}/order
Description
This API is called during the checkout process on the eCommerce site. It pushes the order details from the eCommerce store to the NBOX Now system for processing. The system will handle tasks like calculating the shipping cost, updating the order status, and generating email notifications for the operations team and the user.
Headers
| Name | Description |
|---|---|
x-nbox-shop-token | The token retrieved from the login API. This token authenticates the user. |
x-nbox-shop-domain | The domain of the e-commerce website (e.g., nbox.now) associated with the shop. |
Request
The request body should contain the details of the order, including carrier, customer details, destination, and product information. Below is the structure of the request data:
Main Object Structure
| Name | Type | Required | Description |
|---|---|---|---|
| order | Object | Required | Order details including carrier, order number, subtotal, and shipping fee. |
| customer | Object | Required | Customer information, including name, email, and phone. |
| origin | Object | Required | Origin address of the eCommerce store (shop). Includes address, city, state, and zip code. |
| destination | Object | Required | Shipping destination details, including the recipient's address, city, state, and zip code. |
| products | Array | Required | List of products in the order with attributes such as name, price, quantity, weight, dimensions, and volume. |
Order Object
| Name | Type | Required | Description |
|---|---|---|---|
| shopDomain | String | Required | The domain of the eCommerce store |
| carrier | String | Required | The shipping carrier for the order |
| subTotal | Number | Required | Subtotal amount of the order |
| orderNumber | Number | Required | The unique order number |
| orderReference | String | Required | Reference number for the order |
| total | Number | Required | Total amount of the order |
| currency | String | Required | The currency of the order |
| shippingFee | Number | Required | The shipping fee for the order |
Customer Object
| Name | Type | Required | Description |
|---|---|---|---|
| firstName | String | Required | Customer's first name |
| lastName | String | Required | Customer's last name |
| String | Required | Customer's email address | |
| phone | String | Optional | Customer's phone number |
Origin and Destination Objects
| Name | Type | Required | Description |
|---|---|---|---|
| address | String | Required | Full address, including address lines and any supplementary address info |
| city | String | Required | City |
| state | String | Optional | State or province (accepts null for regions without states) |
| countryCode | String | Required | Country code (e.g., "US", "QA") |
| country | String | Optional | Country Name (e.g., "United States", "Qatar") |
| zip | String | Required | Postal code/Zip code |
| longitude | Number | Optional | Longitude of the address (supports both longitude and lng formats) |
| latitude | Number | Optional | Latitude of the address (supports both latitude and lat formats) |
Product Object
| Name | Type | Required | Description |
|---|---|---|---|
| name | String | Required | Name of the product |
| quantity | Number | Required | Quantity of the product |
| price | Number | Required | Price per unit of the product |
| grams | Number | Required | Weight of the product in grams |
| length | Number | Required | Length of the product in cm |
| width | Number | Required | Width of the product in cm |
| height | Number | Required | Height of the product in cm |
| volume | Number | Required | Volume of the product in cubic centimeters (cm³) |
| currency | String | Required | Currency for the product's price |
Response
| Status | Description |
|---|---|
| 200 OK | Activation successful or failed based on the provided parameters |
| 400 Bad Request | Missing or invalid parameters |
| 401 Unauthorized | Invalid token and/or shop domain |
| 500 Internal Server Error | Server-side error during activation process |
Response Body
The response body will contain the following fields:
| Name | Type | Description |
|---|---|---|
| message | String | Status message indicating success or failure |
| orderId | String | Unique order ID |
| errorDetails | String | Any error details if the order was not processed successfully |
Fulfilled API
Method: POST
Endpoint: POST https://{base_url}/fulfilled
Description
This API is called when an order has been fulfilled (shipped). It pushes the fulfillment status of the order from the eCommerce store to the NBOX Now system for further processing, such as updating the order status or notifying the customer.
Headers
| Name | Description |
|---|---|
x-nbox-shop-token | The token retrieved from the login API. This token authenticates the user. |
x-nbox-shop-domain | The domain of the e-commerce website (e.g., nbox.now) associated with the shop. |
Request
The following parameters should be included in the request body:
| Name | Type | Required | Description |
|---|---|---|---|
| orderNumber | Number | Required | The unique order number |
Response
| Status | Description |
|---|---|
| 200 OK | Activation successful or failed based on the provided parameters |
| 400 Bad Request | Missing or invalid parameters |
| 401 Unauthorized | Invalid token and/or shop domain |
| 500 Internal Server Error | Server-side error during activation process |
Response Body
| Name | Type | Description |
|---|---|---|
| message | String | Status message indicating success or failure |
| orderId | String | Unique order ID |
| errorDetails | String | Any error details if the fulfillment was not processed successfully |
Cancelled API
Method: POST
Endpoint: POST https://{base_url}/order/cancelled
Description
This API is called when an order has been cancelled. It sends the cancellation status from the eCommerce store to the NBOX Now system for further processing, such as updating the order status and notifying the customer of the cancellation.
Headers
| Name | Description |
|---|---|
x-nbox-shop-token | The token retrieved from the login API. This token authenticates the user. |
x-nbox-shop-domain | The domain of the e-commerce website (e.g., nbox.now) associated with the shop. |
Request
| Name | Type | Required | Description |
|---|---|---|---|
| orderNumber | Number | Required | The unique order number |
Response
| Status | Description |
|---|---|
| 200 OK | Activation successful or failed based on the provided parameters |
| 400 Bad Request | Missing or invalid parameters |
| 401 Unauthorized | Invalid token and/or shop domain |
| 500 Internal Server Error | Server-side error during activation process |