Listings API (Developers)¶

The Listing object is the core data model in DMS. Every vehicle/inventory item is a Listing. Retrieve and work with listings through the documented helper functions below rather than instantiating classes directly - the helpers add caching and stay stable across releases.

All helpers live in the global namespace (dms_*) and are safe to call from a theme, child theme, or mu-plugin any time after the dms_init hook has fired.

Retrieving Listings¶

Helper	Returns	Notes
`dms_get_listing( int $listing_id, bool $force_new = false )`	`Listing`	Single listing. Statically cached per request; pass `$force_new = true` to bypass the cache and re-read.
`dms_get_all_listings( array $args = [] )`	`Listing[]`	All listings of a type, keyed by ID. Results cached in the `dms-listing` cache group.
`dms_get_current_listing()`	`Listing\\|null`	The listing currently in context (inside the loop or on a VDP). `null` outside a listing context.
`dms_get_current_listing_id()`	`int`	ID of the current listing, or `0` if none.

`dms_get_listing()`¶

$listing = dms_get_listing( 123 );

if ( $listing->exists() ) {
    echo esc_html( $listing->get_title() );
    echo esc_html( $listing->get_formatted_price() );
}

Always guard with $listing->exists() - an unknown ID still returns a Listing object, just an empty one.

`dms_get_all_listings()`¶

$args accepts standard WP_Query arguments plus two DMS-specific keys:

Key	Type	Purpose
`type`	`Type`	The inventory type to pull from. Defaults to the current type when omitted.
`select`	`bool`	When `true`, returns `[ id => post_title ]` pairs instead of `Listing` objects - handy for building `<select>` dropdowns.

// Every listing of the current type
$listings = dms_get_all_listings();

// A specific type, only 10, ordered by title
$type = dms_get_type( 'vehicles' );
$listings = dms_get_all_listings( [
    'type'           => $type,
    'posts_per_page' => 10,
    'orderby'        => 'title',
    'order'          => 'ASC',
] );

foreach ( $listings as $id => $listing ) {
    echo esc_html( $listing->get_title() );
}

Note: dms_get_all_listings() loads full Listing objects for every match. For large inventories, prefer a narrower query (dms_listing_query() / DMS_Query) or the select shortcut.

The `Listing` Object¶

Once you have a Listing, these are the commonly used public getters. All are safe to call; getters return sensible empty values when data is missing.

Identity & existence¶

Method	Returns	Purpose
`get_id()`	`int`	The listing (post) ID.
`exists()`	`bool`	Whether this ID resolves to a real listing. Always check first.
`get_title()`	`string`	The listing title.
`get_permalink()`	`string`	Public URL (VDP).
`get_edit_link()`	`string\\|null`	Admin edit URL, or `null` if the user can't edit.
`get_type()`	`Type`	The inventory `Type` this listing belongs to.
`get_status()`	`string`	Current listing status slug.
`is_published()`	`bool`	Whether the listing is published.

Reading field values¶

Listing field values live in categories (DMS's term for structured attributes like make, model, color) and in raw post meta. Prefer get_term() for category-backed fields.

Method	Returns	Purpose
`get_term( int $category_id, bool $full_term = false )`	`string\\|array\\|Term`	The selected value for a category. `$full_term = true` returns the full `Term` object (or file array for file categories) instead of the display string.
`get_terms( int $category_id, bool $full_term = false )`	`string\\|array\\|Term`	Same as above for multi-value categories; returns all selected terms.
`get_meta( string $key, bool $is_single = true )`	`mixed`	Raw post meta value. Use for meta not modelled as a category.
`get( string $name, mixed $default_value = null )`	`mixed`	Generic property accessor with a fallback default.
`get_post_content( int $max_chars = 0, string $ellipsis = '...' )`	`string`	The listing description, optionally truncated.

$listing = dms_get_current_listing();

// Category-backed field (e.g. category ID 42 = "Exterior Color")
$color = $listing->get_term( 42 );

// Raw meta
$vin = $listing->get_meta( 'dms_vin' );

Category IDs are stable numeric IDs. Find a category's ID under Dealer.ms → (type) → Categories, or resolve one by slug with dms_get_category( 'exterior-color' )->get_id().

Writing values¶

Writes persist immediately to the database. Use sparingly on the front end.

Method	Returns	Purpose
`set_title( $title )`	`WP_Error\\|bool\\|int`	Update the title.
`update_meta( string $key, string\\|int\\|array $value, int $category_id = 0 )`	`void`	Write a meta value; pass a `$category_id` for category-backed fields.
`set_status( $status )`	`void`	Change the listing status.
`set_sold( bool $is_sold )`	`int\\|bool`	Mark sold / unsold.
`set_sale_pending( bool $is_pending )`	`int\\|bool`	Mark sale pending.
`set_coming_soon( bool $coming_soon )`	`mixed`	Toggle coming-soon.
`set_badge( int $badge_id )` / `remove_badge()`	`void`	Assign / clear a badge.

Status flags¶

Method	Returns
`is_sold()`	`bool`
`is_sale_pending()`	`bool`
`is_coming_soon()`	`bool`
`is_visible()`	`bool`
`is_price_locked()`	`bool`
`is_compared()`	`bool`

Images & media¶

Method	Returns	Purpose
`get_main_image_id()`	`int`	Attachment ID of the primary image.
`get_main_image( string $image_size = 'dms-listing-main' )`	`array`	Primary image data (url/width/height).
`has_gallery_images()`	`bool`	Whether the gallery has any images.
`get_gallery_images( string $image_size = 'full', bool $show_not_found = true, mixed $filter_category = false, bool $include_all_types = false )`	`array`	Gallery image set, optionally filtered by image category.
`get_video()`	`string`	Video URL/embed.

Pricing, fees & discounts¶

DMS separates the base price, per-listing/per-type fees & discounts, and the final price.

Method	Returns	Purpose
`get_price( string $type = 'price' )`	`float`	Raw numeric price. `$type` selects which stored price (`price`, `original`, etc.).
`get_formatted_price( string $type = 'price' )`	`string`	Price formatted with the site's currency settings.
`get_fees_total()`	`float`	Sum of applicable fees.
`get_discounts_total()`	`float`	Sum of applicable discounts.
`get_final_price()`	`float`	Price after fees and discounts.
`get_formatted_final_price()`	`string`	Final price, currency-formatted.
`get_fees_discounts()`	`array`	Full list of resolved fee/discount line items for this listing.
`get_fee_discount( string $id )`	`array\\|null`	A single fee/discount line item by its reference ID.
`has_discount()`	`bool`	Whether any discount applies.
`get_discount()`	`array`	The active discount details.

$listing = dms_get_current_listing();

echo $listing->get_formatted_price();        // base price, e.g. "$24,995"
echo $listing->get_formatted_final_price();  // after fees/discounts

foreach ( $listing->get_fees_discounts() as $line ) {
    printf( '%s: %s', esc_html( $line['name'] ), esc_html( dms_format_price( $line['amount'] ) ) );
}

To modify a listing's price at runtime (e.g. a promotional discount) use apply_discount():

// 10% off, overwriting any existing discount
$listing->apply_discount( 10, 'percent', 'overwrite', 'summer-sale' );
$listing->clear_discount();

Analytics & misc¶

Method	Returns	Purpose
`get_views( $view_type )`	`int`	View count. `$view_type` is `'unique'` or `'total'`.
`get_total_leads()`	`int`	Number of leads attributed to this listing.
`get_days_on_lot()`	`int`	Days since the listing was acquired/added.
`get_seo_score()`	`mixed`	Stored SEO score.
`get_next_listing()` / `get_prev_listing()`	`mixed`	Adjacent listings in the current query context.

Inventory Types¶

A Type (e.g. "Vehicles", "Trailers") is a custom post type plus its DMS configuration.

Helper	Returns	Notes
`dms_get_types( bool $array_format = false )`	`Type[]`	All types. `$array_format = true` returns an array of post-type slugs instead.
`dms_get_type( int\\|string $id )`	`Type`	A single type by ID or slug.
`dms_get_current_type()`	`Type`	The type in context (SRP, VDP, admin edit, AJAX, Elementor preview). Returns an empty `Type(0)` when none.
`dms_set_current_type( int $type_id )`	`void`	Force the current type (sets the `dms-type` query var).
`dms_get_type_options()`	`array`	All type option definitions.
`dms_is_dms_post_type( string $post_type )`	`bool`	Whether a post-type slug belongs to DMS.
`dms_listing_types_to_select_options( array $args = [] )`	`array`	Types as `value => label` pairs for a dropdown.

The `Type` object¶

Method	Returns	Purpose
`get_id()`	`int`	Type ID.
`exists()`	`bool`	Whether this is a real type.
`get( string $value, $default = false )`	`mixed`	Any type setting: `slug`, `singular`, `plural`, `vdp_template`, etc.
`get_categories( array $filter = [] )`	`array`	The type's categories (attribute definitions).
`get_badges( array $args = [] )`	`array`	Badges configured for the type.
`get_groups()`	`array`	Listing groups.
`get_price_value( string $min_or_max = 'min' )`	`int`	Min/max price across the type's inventory.
`get_link( string $link_type, bool $full_url = false )`	`string`	A type-level URL (e.g. its SRP).

$type = dms_get_current_type();

if ( $type->exists() ) {
    echo $type->get( 'plural' );   // "Vehicles"
    echo $type->get( 'singular' ); // "Vehicle"
    echo $type->get( 'slug' );     // post-type slug
}

Querying Listings¶

For custom lists, filters, and result counts, work through the listing query layer rather than a bare WP_Query - it understands DMS categories, terms, and price ordering.

Helper	Returns	Purpose
`dms_listing_query()`	`Query\\|null`	The shared listing-query singleton (SRP context).
`dms_get_listing_query()`	query result	The underlying `WP_Query`-like result of the current SRP query.
`dms_get_total_listings()`	`int`	`found_posts` for the current query (filterable via `dms_total_listings`).
`dms_get_selected_terms()`	`array`	Terms the visitor has selected as filters on the current SRP.
`dms_set_current_listing( int\\|Listing $listing, bool $is_main_query = false )`	`void`	Set the current listing in context (e.g. to render a template for a specific listing).
`dms_reset_current_listing()`	`void`	Restore the main queried listing.
`dms_add_listing_filter( Category $category, Term $term )`	`void`	Programmatically add a category/term filter to the current query.
`dms_get_listing_orderby_args( string $orderby_key, string $direction = 'desc', int $type_id = 0 )`	`array`	Build `orderby` + `meta_query` args matching SRP ordering. Accepts `date`, `dms_price`, `dms_discount`, the `dms_date_*` keys, or a numeric category ID.

Direct queries with `DMS_Query`¶

DMS_Query is a WP_Query wrapper that adds DMS-aware arguments (type_id, category meta keys, price ordering). Use it for one-off custom loops.

$type = dms_get_type( 'vehicles' );

$query = new DMS_Query( [
    'type_id'        => $type->get_id(),
    'posts_per_page' => 6,
    'fields'         => 'ids',
    'meta_query'     => [
        [
            'key'     => dms_category_meta_key( $make_category_id ),
            'value'   => 'Toyota',
            'compare' => '=',
        ],
    ],
] );

foreach ( $query->get_posts() as $listing_id ) {
    $listing = dms_get_listing( $listing_id );
    echo esc_html( $listing->get_title() );
}

Resolve a category's meta key with dms_category_meta_key( $category_id ) - never hardcode meta keys.

Page Context Helpers¶

Use these to branch behaviour by page type. Each optionally scopes to an inventory type.

Helper	Returns	True when
`dms_is_srp( int\\|string $type = 0 )`	`bool`	On a Search Results Page.
`dms_is_vdp( int\\|string $type = 0 )`	`bool`	On a Vehicle Details Page.
`dms_is_comparison( int\\|string $type = 0 )`	`bool`	On a comparison page.
`dms_is_dms()`	`bool`	On any DMS-controlled page.

add_action( 'wp_footer', function () {
    if ( dms_is_vdp() ) {
        $listing = dms_get_current_listing();
        // e.g. inject structured data for this vehicle
    }
} );