4.1 Create product

POST /api/v1/gateway/products/create

Register a new product for your vendor. The product is created with status pending (requires admin approval before it can be used in packages).

Request

Headers: HVMX-MERCHANT-ID, HVMX-API-KEY, Content-Type: application/json

Body:

Example request body:

{
  "name": "Cotton Crew Neck T-Shirt",
  "weight": 0.3,
  "price": 2499,
  "description": "Soft cotton, regular fit. Available in multiple sizes.",
  "product_type_id": 1,
  "dimension_width": 25,
  "dimension_height": 2,
  "dimension_length": 35
}

Success (201 Created): status: 1, message, data with created product (id, name, weight, price, description, product_type_id, dimensions, flag: 2 = pending, created_at).

Error (400): status: 0, message describes the issue. Response may include log_id.

4.2 Get product types

GET /api/v1/gateway/products/types

Returns the list of active product types (for dropdowns and when creating products).

Headers: HVMX-MERCHANT-ID, HVMX-API-KEY. Body: None.

Success (200): status: 1, data = array of { "id": number, "name": string }.

{
  "status": 1,
  "message": "OK",
  "data": [
    { "id": 1, "name": "Apparel" },
    { "id": 2, "name": "Accessories" }
  ]
}

5.1 Create package

POST /api/v1/gateway/packages/create

Create a new package. The package is created in status ready for pickup and a first journey step is recorded. Delivery route is resolved from the receiver address.

Request body

collection_type — what is collected at delivery

Choose how much the customer pays when the package is delivered:

Example request body:

{
  "weight": 1.2,
  "price": 8500,
  "receiver_name": "Nadeera Fernando",
  "receiver_phone": "+94112345678",
  "receiver_address": "45 Galle Road, Colombo 03",
  "collection_type": "delivery_fee_with_package_price",
  "custom_package_id": "SHOP-2024-1847",
  "products": [
    { "product_id": 10, "quantity": 2 },
    { "product_id": 11, "quantity": 1 }
  ]
}

Success (201): data = package object (same shape as Package Details). Error (400): e.g. duplicate custom_package_id, invalid address; may include log_id.

5.2 List packages

GET /api/v1/gateway/packages/list/:page

List packages for the authenticated vendor (ecommerce_api only). Paginated, 100 per page.

URL parameters: page — Page number (1-based). Example: GET /api/v1/gateway/packages/list/1

Success (200): data.packages = array of Package objects; data.pagination = { page, per_page, total, total_pages }.

{
  "status": 1,
  "message": "OK",
  "data": {
    "packages": [
      {
        "id": 1,
        "package_id": "D1C2ABC123",
        "custom_package_id": "SHOP-2024-1847",
        "package_status": "pending",
        "weight": 1.2,
        "price": 8500,
        "delivery_fee": 250,
        "total_price": 8750,
        "collection_type": "delivery_fee_with_package_price",
        "receiver_name": "Nadeera Fernando",
        "receiver_phone": "+94112345678",
        "receiver_address": "45 Galle Road, Colombo 03",
        "delivery_date": "",
        "created_at": "2024-02-28T10:30:00.000Z",
        "products": [
          { "product_id": 10, "product_name": "Cotton T-Shirt (Blue)", "total_price": 5000 },
          { "product_id": 11, "product_name": "Denim Jacket", "total_price": 3500 }
        ]
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 100,
      "total": 1,
      "total_pages": 1
    }
  }
}

5.3 Get package details

POST /api/v1/gateway/packages/details

Get a single package by its package_id (system-generated, e.g. D1C2ABC123). Only packages belonging to the vendor and with create_type = ecommerce_api are returned.

Body: { "package_id": "D1C2ABC123" }

Success (200): data = Package object. Not found (404): status: 0, message: "Package not found".

5.4 Get delivery fee

POST /api/v1/gateway/packages/delivery-fee

Calculate delivery fee by city name and weight. Uses the same pricing slab logic as package creation. If city is not found, Colombo rates are applied and city_status reflects that.

Body: city (optional, string), weight (required, number > 0). Example: { "city": "Colombo", "weight": 1.2 }

Success (200): data = { delivery_fee, recognized_city, city_status, weight }.

{
  "status": 1,
  "message": "City recognized successfully.",
  "data": {
    "delivery_fee": 250,
    "recognized_city": "Colombo",
    "city_status": "City recognized successfully.",
    "weight": 1.2
  }
}