Adding a new ‘reservationDealId’ field to the Stock API

Advisory notice of a new ‘reservationDealId’ field being added to the stock API.

Over the last year, we’ve been working with retailers to enable new digital services on Auto Trader, allowing consumers to complete more of their buying journey online. More than 1,000 retailers are currently trialling this new solution, which you may recognise as Deal Builder. Today, when a vehicle is reserved on Auto Trader you will be able to view the updates to the ‘reservationStatus’ property with the value “Reserved By Auto Trader”.

Last week we enabled a new feature which provides retailers on the trial with visibility of unreserved deals. This is where a consumer has completed a finance application but has not gone on to submit the deal and pay the reservation fee by 9am the following day. To support this feature, we're now introducing a new ‘reservationDealId’ field in the stock API.

What is changing?

Retailers will now be notified of unreserved deals in Portal. This means that deals may now exist for a vehicle where the reservationStatus is still set to ‘null’.

As part of the change retailers will now be able to manually reserve stock in Portal for a specific deal. This action will populate the new reservationDealId field for the specified deal in the Stock API. Once a reservationDealId is set, the lifecycleState of the stock item will be automatically progressed to SALE_IN_PROGRESS.

This will remove the ability for any new deals to be created against the stock item but retailers will still be able to manage the deal through to completion, similar to how reservations currently work today.

Technical details are available in our developer documentation on the newly added field. If you require assistance with implementing the changes, please contact our Technical Account Management Team on: technicalaccountmanagement@autotrader.co.uk

Impacts to lifecycleState with a reservationDealId present

The changes above will also have a small impact on how lifecycleState is updated when there is a reservationDealId:

When a reservationDealId is present, there is an active deal against the stock item, and it will be automatically progressed through the necessary lifecycleState’s starting at SALE_IN_PROGRESS and ending in SOLD or returned to FORECOURT depending on the outcome of the deal (Completed or Cancelled respectively). When deals are in this state it is important to not update the lifecycleState as this will be done automatically as previously described and any further modification to lifecycleState will impact a retailer’s ability to manage those deals.

Please note: Deals may still be available for a retailer to manage even when a reservationDealId is not set. Therefore it is essential that lifecycleState is only updated to SOLD when the vehicle has been sold and to DELETED when there is no need to access the stock.

IMPORTANT: From the 1st May 2024 we will be introducing a change that will prevent Partners from directly updating the lifecycleState once reservationDealId is populated.

Example of how the lifecycleState will automatically progress in the Deal Builder journey.

Publishing or unpublishing the stock item on Auto Trader, or any other channel, will remain unaffected by these changes.

A full overview of the changes can be seen in our developer documentation and if you need any assistance please reach out to our Technical Account Management team on: technicalaccountmanagement@autotrader.co.uk