Listings API

Create, read, update, and delete vehicle listings programmatically.

Endpoints Overview

Public Endpoints (No Auth Required)

Method	Endpoint	Description
GET	`/api/listings`	List all active listings
GET	`/api/listings/trending`	Get trending listings
GET	`/api/listings/featured`	Get featured listings
GET	`/api/listings/:slug`	Get single listing by slug
GET	`/api/listings/:slug/related`	Get related listings

Seller Endpoints (SELLER Role Required)

Method	Endpoint	Description
GET	`/api/seller/listings`	List seller's own listings
GET	`/api/seller/listings/:id`	Get listing by ID
POST	`/api/seller/listings`	Create new listing
PUT	`/api/seller/listings/:id`	Update listing
DELETE	`/api/seller/listings/:id`	Soft delete listing
POST	`/api/seller/listings/:id/publish`	Submit for review
POST	`/api/seller/listings/:id/mark-sold`	Mark as sold
POST	`/api/seller/listings/:id/renew`	Extend listing expiry
POST	`/api/seller/listings/:id/duplicate`	Clone as draft
POST	`/api/seller/listings/:id/images`	Upload images
PUT	`/api/seller/listings/:id/images/reorder`	Reorder images
DELETE	`/api/seller/listings/:id/images/:imageId`	Delete image

Bulk Operations (SELLER Role Required)

Method	Endpoint	Description
POST	`/api/seller/listings/bulk/pause`	Pause multiple listings
POST	`/api/seller/listings/bulk/activate`	Re-activate listings
POST	`/api/seller/listings/bulk/delete`	Delete multiple listings
GET	`/api/seller/bulk-import/template`	Download CSV template
POST	`/api/seller/bulk-import/upload`	Upload CSV import
GET	`/api/seller/bulk-import/xml-schema`	Download XSD schema
POST	`/api/seller/bulk-import/xml`	Upload XML import
GET	`/api/seller/bulk-import/history`	Get import history

List Listings

Retrieve a paginated list of listings.

Request

bash

GET /v1/listings
Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`limit`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status: active, draft, sold
`category`	string	Filter by category slug
`sort`	string	Sort field: created_at, price, year
`order`	string	Sort order: asc, desc

Response

json

{
  "success": true,
  "data": {
    "listings": [
      {
        "id": "lst_abc123",
        "title": "2021 Volvo FH 500 Euro 6",
        "slug": "2021-volvo-fh-500-euro-6",
        "price": 85000,
        "currency": "EUR",
        "status": "active",
        "category": {
          "id": "cat_trucks",
          "name": "Trucks"
        },
        "brand": {
          "id": "brd_volvo",
          "name": "Volvo"
        },
        "year": 2021,
        "mileage": 245000,
        "images": [
          {
            "url": "https://cdn.menonmobility.com/img1.jpg",
            "thumbnail": "https://cdn.menonmobility.com/img1_thumb.jpg"
          }
        ],
        "location": {
          "country": "Germany",
          "city": "Munich"
        },
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-15T10:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "total_pages": 3
    }
  }
}

Get Single Listing

Retrieve detailed information about a specific listing.

Request

bash

GET /v1/listings/lst_abc123
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "success": true,
  "data": {
    "id": "lst_abc123",
    "title": "2021 Volvo FH 500 Euro 6",
    "slug": "2021-volvo-fh-500-euro-6",
    "description": "Full vehicle description...",
    "price": 85000,
    "currency": "EUR",
    "price_negotiable": true,
    "status": "active",
    "category": {
      "id": "cat_trucks",
      "name": "Trucks",
      "slug": "trucks"
    },
    "subcategory": {
      "id": "sub_semi",
      "name": "Semi Trucks",
      "slug": "semi-trucks"
    },
    "brand": {
      "id": "brd_volvo",
      "name": "Volvo"
    },
    "model": "FH 500",
    "year": 2021,
    "mileage": 245000,
    "mileage_unit": "km",
    "condition": "used",
    "specifications": {
      "fuel_type": "diesel",
      "transmission": "automatic",
      "engine_power": 500,
      "engine_power_unit": "hp",
      "euro_standard": "euro6",
      "drive_type": "4x2",
      "axles": 2
    },
    "features": [
      "air_conditioning",
      "cruise_control",
      "sleeper_cab",
      "navigation"
    ],
    "images": [
      {
        "id": "img_1",
        "url": "https://cdn.menonmobility.com/img1.jpg",
        "thumbnail": "https://cdn.menonmobility.com/img1_thumb.jpg",
        "order": 1
      }
    ],
    "location": {
      "country": "Germany",
      "country_code": "DE",
      "region": "Bavaria",
      "city": "Munich",
      "coordinates": {
        "lat": 48.1351,
        "lng": 11.5820
      }
    },
    "seller": {
      "id": "usr_seller123",
      "name": "ABC Trucks GmbH",
      "type": "business",
      "verified": true
    },
    "views": 1250,
    "favorites": 45,
    "featured": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "published_at": "2024-01-15T10:30:00Z"
  }
}

Create Listing

Create a new vehicle listing.

Request

bash

POST /v1/listings
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body

json

{
  "title": "2021 Volvo FH 500 Euro 6",
  "description": "Well-maintained truck with full service history...",
  "price": 85000,
  "currency": "EUR",
  "price_negotiable": true,
  "category_id": "cat_trucks",
  "subcategory_id": "sub_semi",
  "brand_id": "brd_volvo",
  "model": "FH 500",
  "year": 2021,
  "mileage": 245000,
  "mileage_unit": "km",
  "condition": "used",
  "specifications": {
    "fuel_type": "diesel",
    "transmission": "automatic",
    "engine_power": 500,
    "engine_power_unit": "hp",
    "euro_standard": "euro6",
    "drive_type": "4x2"
  },
  "features": ["air_conditioning", "cruise_control", "sleeper_cab"],
  "location": {
    "country_code": "DE",
    "city": "Munich",
    "address": "123 Example Street"
  },
  "publish": false
}

Required Fields

Field	Type	Description
`title`	string	Listing title
`category_id`	string	Category ID
`brand_id`	string	Brand ID
`price`	number	Price amount
`currency`	string	Currency code (EUR, USD, etc.)
`year`	integer	Manufacturing year
`condition`	string	new, used, certified

Response

json

{
  "success": true,
  "data": {
    "id": "lst_new123",
    "title": "2021 Volvo FH 500 Euro 6",
    "status": "draft",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Update Listing

Update an existing listing.

Request

bash

PUT /v1/listings/lst_abc123
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body

Send only the fields you want to update:

json

{
  "price": 82000,
  "price_negotiable": false,
  "description": "Updated description..."
}

Response

json

{
  "success": true,
  "data": {
    "id": "lst_abc123",
    "title": "2021 Volvo FH 500 Euro 6",
    "price": 82000,
    "updated_at": "2024-01-16T14:20:00Z"
  }
}

Delete Listing

Delete a listing.

Request

bash

DELETE /v1/listings/lst_abc123
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "success": true,
  "data": {
    "id": "lst_abc123",
    "deleted": true
  }
}

Publish/Unpublish

Publish Listing

bash

POST /v1/listings/lst_abc123/publish
Authorization: Bearer YOUR_API_KEY

Unpublish Listing

bash

POST /v1/listings/lst_abc123/unpublish
Authorization: Bearer YOUR_API_KEY

Upload Images

Request

bash

POST /v1/listings/lst_abc123/images
Authorization: Bearer YOUR_API_KEY
Content-Type: multipart/form-data

Form Data

Field	Type	Description
`images[]`	file	Image files (multiple)
`order[]`	integer	Display order

Response

json

{
  "success": true,
  "data": {
    "images": [
      {
        "id": "img_new1",
        "url": "https://cdn.menonmobility.com/new1.jpg",
        "thumbnail": "https://cdn.menonmobility.com/new1_thumb.jpg",
        "order": 1
      }
    ]
  }
}

Delete Image

bash

DELETE /v1/listings/lst_abc123/images/img_1
Authorization: Bearer YOUR_API_KEY

Bulk Operations

Bulk Update Status

bash

POST /v1/listings/bulk/status
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "listing_ids": ["lst_1", "lst_2", "lst_3"],
  "status": "sold"
}

Bulk Update Price

bash

POST /v1/listings/bulk/price
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "listing_ids": ["lst_1", "lst_2"],
  "adjustment_type": "percentage",
  "adjustment_value": -10
}

Error Codes

Code	Description
`LISTING_NOT_FOUND`	Listing does not exist
`LISTING_LIMIT_EXCEEDED`	Plan listing limit reached
`INVALID_CATEGORY`	Category ID is invalid
`INVALID_BRAND`	Brand ID is invalid
`VALIDATION_ERROR`	Request validation failed

Listings API ​

Endpoints Overview ​

Public Endpoints (No Auth Required) ​

Seller Endpoints (SELLER Role Required) ​

Bulk Operations (SELLER Role Required) ​

List Listings ​

Request ​

Query Parameters ​

Response ​

Get Single Listing ​

Request ​

Response ​

Create Listing ​

Request ​

Body ​

Required Fields ​

Response ​

Update Listing ​

Request ​

Body ​

Response ​

Delete Listing ​

Request ​

Response ​

Publish/Unpublish ​

Publish Listing ​

Unpublish Listing ​

Upload Images ​

Request ​

Form Data ​

Response ​

Delete Image ​

Bulk Operations ​

Bulk Update Status ​

Bulk Update Price ​

Error Codes ​

Related Topics ​

Listings API

Endpoints Overview

Public Endpoints (No Auth Required)

Seller Endpoints (SELLER Role Required)

Bulk Operations (SELLER Role Required)

List Listings

Request

Query Parameters

Response

Get Single Listing

Request

Response

Create Listing

Request

Body

Required Fields

Response

Update Listing

Request

Body

Response

Delete Listing

Request

Response

Publish/Unpublish

Publish Listing

Unpublish Listing

Upload Images

Request

Form Data

Response

Delete Image

Bulk Operations

Bulk Update Status

Bulk Update Price

Error Codes

Related Topics