Sellora API Documentation

Introduction

Sellora provides hassle‑free, powerful shipping APIs for your platforms such as websites, e‑commerce stores, ERPs, and more.

Sellora APIs allow you to get rates, create and track shipments, validate addresses, and manage logistics without leaving your main platform. The API is RESTful and uses JSON for requests and responses.

Get Started

All API endpoints listed in this documentation are relative to:

https://sellora.ng/api/v1

Before you begin:

1. Create an account: https://sellora.ng/register
2. Visit Profile in your dashboard
3. Generate an API key 
4. Keep your API keys secure

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

The API will validate your key and return a 401 error if the key is invalid or inactive.

Validate Address

Validates and geocodes a delivery or pickup address. You must validate your pickup address before creating shipments.

POST /address/validate

Request Body

Field	Type	Required	Description
name	string	REQUIRED	Full name of the person at this address
email	string	REQUIRED	Email address (valid email format)
phone	string	REQUIRED	Phone number with country code (e.g., +2348012345678)
address	string	REQUIRED	Complete address including street, city, state, country

Response Example

{
  "success": true,
  "data": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+2348012345678",
    "address_code": 12345678,
    "postal_code": "101233",
    "formatted_address": "123 Main Street, Lagos, Nigeria",
    "message": "Address validated successfully"
  },
  "timestamp": "2025-12-16T10:27:08+00:00"
}

Get Rates

Retrieves shipping rates from multiple courier services based on package details and destinations.

POST /rates

Request Body

Field	Type	Required	Description
sender_address_code	integer	OPTIONAL	Address code from /address/validate. If not provided, uses your account's validated pickup address
receiver_address_code	integer	REQUIRED	Receiver's address code obtained from /address/validate
category_id	integer	REQUIRED	Package category ID from /categories endpoint
package_dimension	object	REQUIRED	Object containing length, width, height (all in CM, as integers)
pickup_date	string	REQUIRED	Pickup date in format: "Year-Month-Day" (e.g., "2025-12-20")
package_items	array	REQUIRED	Array of item objects (see below)
delivery_instructions	string	OPTIONAL	Special delivery instructions for the courier
service_type	string	OPTIONAL	Filter by service type: "pickup" or "dropoff"

Package Items Object Structure

Field	Type	Required	Description
name	string	REQUIRED	Item name
description	string	REQUIRED	Item description
unit_weight	float	REQUIRED	Weight per unit in kilograms (e.g., 0.5 for 500g)
unit_amount	float	REQUIRED	Price per unit in NGN
quantity	integer	REQUIRED	Number of units

Request Example

{
  "receiver_address_code": 87654321,
  "category_id": 98190590,
  "package_dimension": {
    "length": 30,
    "width": 20,
    "height": 15
  },
  "pickup_date": "2025-12-25",
  "package_items": [
    {
      "name": "Laptop",
      "description": "Dell XPS 15",
      "unit_weight": 2.5,
      "unit_amount": 500000,
      "quantity": 1
    }
  ],
  "delivery_instructions": "Handle with care"
}

Response Example

{
  "success": true,
  "data": {
    "status": "success",
    "message": "Retrieved successfully",
    "data": {
      "request_token": "b724643e35047b44bf6499ce32dec6bf44b4de88859c03198a6f5714e026173b",
      "couriers": [
        {
          "courier_id": "cora",
          "courier_name": "Cora",
          "service_code": "cora",
          "service_type": "pickup",
          "total": 3063,
          "currency": "NGN",
          "vat": 188,
          "pickup_eta": "Within 3 hours",
          "delivery_eta": "Within 23 hrs",
          "tracking_level": 7,
          "ratings": 3
        }
      ],
      "fastest_courier": {
        "courier_name": "Routely (Express Premium)",
        "total": 3308,
        "delivery_eta": "Within 9 hrs"
      },
      "cheapest_courier": {
        "courier_name": "Dellyman",
        "total": 400,
        "delivery_eta": "Within 1 - 2 working days"
      }
    }
  },
  "timestamp": "2025-12-16T10:27:08+00:00"
}

Create Shipment

Creates a new shipment using a request token from the rates endpoint.

POST /shipments

Request Body

Field	Type	Required	Description
request_token	string	REQUIRED	Token received from /rates endpoint
service_code	string	REQUIRED	Service code of selected courier (e.g., "cora", "routely")
courier_id	string	REQUIRED	Courier ID from the selected rate

Request Example

{
  "request_token": "b724643e35047b44bf6499ce32dec6bf44b4de88859c03198a6f5714e026173b",
  "service_code": "cora",
  "courier_id": "cora"
}

Response Example

{
  "success": true,
  "data": {
    "shipment": {
      "order_id": "SB-2CF48224272",
      "status": "pending",
      "courier": {
        "name": "Cora",
        "email": "cora@cora.com",
        "phone": "010000038198"
      },
      "ship_from": {
        "name": "John Doe",
        "phone": "+2348012345678",
        "email": "john@example.com",
        "address": "123 Main Street, Lagos, Nigeria"
      },
      "ship_to": {
        "name": "Jane Smith",
        "phone": "+2348087654321",
        "email": "jane@example.com",
        "address": "456 Market Road, Lagos, Nigeria"
      },
      "payment": {
        "shipping_fee": 3063,
        "type": "wallet",
        "status": "completed",
        "currency": "NGN"
      },
      "items": [
        {
          "name": "Laptop",
          "description": "Dell XPS 15",
          "weight": 2.5,
          "amount": "500000",
          "quantity": "1",
          "total": 500000
        }
      ],
      "tracking_url": "https://sellora.ng/shipments/track?shipment_id?=SB-2CF48224272",
      "date": "2025-12-16 14:30:00"
    },
    "message": "Shipment created successfully"
  },
  "timestamp": "2025-12-16T10:27:08+00:00"
}

Track Shipment

Retrieves tracking information and status updates for a specific shipment.

GET /shipments/track?shipment_id=SB123

URL Parameters

Parameter	Type	Required	Description
shipment_id	string	REQUIRED	Shipment ID (e.g., SB-2CF48224272) received when creating shipment

Response Example

{
  "success": true,
  "data": {
    "status": "success",
    "message": "Retrieved successfully",
    "data": [
      {
        "date": "2025-12-13T14:00:35.000Z",
        "order_id": "SB-4102465CAA5F",
        "status": "in_transit",
        "courier": {
          "name": "Cora",
          "tracking_code": "CORA12345",
          "tracking_message": "Package out for delivery",
          "rider_info": {
            "name": "John Driver",
            "phone": "+2348011112222"
          }
        },
        "delivery_eta": "Within 2 hours",
        "package_status": [
          {
            "status": "Pending",
            "datetime": "2025-12-13T14:00:35.000Z"
          },
          {
            "status": "Picked Up",
            "datetime": "2025-12-13T15:30:00.000Z"
          },
          {
            "status": "In Transit",
            "datetime": "2025-12-13T16:45:00.000Z"
          }
        ],
        "tracking_url": "https://sellora.ng/shipments/track?shipment_id?=SB-2CF48224272"
      }
    ]
  },
  "timestamp": "2025-12-16T10:27:55+00:00"
}

List Shipments

Retrieves a paginated list of all shipments created through your API account.

GET /shipments?limit=50&offset=0

URL Parameters

Parameter	Type	Required	Description
limit	integer	OPTIONAL	Number of records to return (default: 50, max: 100)
offset	integer	OPTIONAL	Number of records to skip for pagination (default: 0)
status	string	OPTIONAL	Filter by status: pending, in_transit, delivered, cancelled

Response Example

{
  "success": true,
  "data": {
    "shipments": [
      {
        "shipment_id": "SB-2CF48224272",
        "customer_name": "Jane Smith",
        "customer_phone": "+2348087654321",
        "delivery_address": "456 Market Road, Lagos, Nigeria",
        "item_name": "Laptop",
        "courier_name": "Cora",
        "shipment_status": "delivered",
        "created_at": "2025-12-15 10:30:00"
      }
    ],
    "pagination": {
      "total": 150,
      "limit": 50,
      "offset": 0
    }
  },
  "timestamp": "2025-12-16T10:27:08+00:00"
}

Cancel Shipment

Cancels a pending shipment. Note: Only shipments in "pending" status can be cancelled.

POST /shipments/cancel

Request Body

Field	Type	Required	Description
shipment_id	string	REQUIRED	Shipment ID to cancel (e.g., SB-2CF48224272)

Request Example

{
  "shipment_id": "SB-2CF48224272"
}

Response Example

{
  "success": true,
  "data": {
    "status": "success",
    "message": "Shipment successfully cancelled"
  },
  "timestamp": "2025-12-16T10:27:08+00:00"
}

Get Categories

Retrieves all available package categories. Use the category_id when getting rates.

GET /categories

Response Example

{
  "success": true,
  "data": {
    "status": "success",
    "message": "Retrieved successfully",
    "data": [
      {
        "category_id": 98190590,
        "category": "Hot food"
      },
      {
        "category_id": 2178251,
        "category": "Groceries"
      },
      {
        "category_id": 67658572,
        "category": "Sensitive items (ATM cards, documents)"
      },
      {
        "category_id": 20754594,
        "category": "Light weight items"
      }
    ]
  },
  "timestamp": "2025-12-16T10:27:08+00:00"
}

Get Dimensions

Retrieves predefined package dimensions with their specifications. Use these as reference when specifying package_dimension in the rates endpoint.

GET /dimensions

Response Example

{
  "success": true,
  "data": {
    "status": "success",
    "message": "Retrieved successfully",
    "data": [
      {
        "name": "Envelope",
        "description_image_url": "https://res.cloudinary.com/delivry/image/upload/v1651839241/package_boxes/envelope-removebg-preview_ghzcii.png",
        "height": 2,
        "width": 35,
        "length": 25,
        "max_weight": 0.5
      },
      {
        "name": "Large Box 2",
        "description_image_url": "https://res.cloudinary.com/delivry/image/upload/v1712625408/package_boxes/Gemini_Generated_Image_iv8xi3iv8xi3iv8x_x8px9t.jpg",
        "height": 39,
        "width": 40,
        "length": 48,
        "max_weight": 25
      },
      {
        "name": "Large Box 3",
        "description_image_url": "https://res.cloudinary.com/delivry/image/upload/v1712625560/package_boxes/Gemini_Generated_Image_tb5yhrtb5yhrtb5y_ohaund.jpg",
        "height": 45,
        "width": 50,
        "length": 56,
        "max_weight": 40
      }
    ]
  },
  "timestamp": "2025-12-16T10:26:18+00:00"
}

Note: All dimensions are in centimeters (CM) and max_weight is in kilograms (KG).

Account Info

Retrieves information about your API account including pickup address and settings.

GET /account

Response Example

{
  "success": true,
  "data": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "08012345678",
    "pickup_address": "123 Main Street, Lagos, Nigeria",
    "address_validated": true,
    "auto_shipment_enabled": true
  },
  "timestamp": "2025-12-16T10:25:38+00:00"
}