PHPackages                             northbees/autotrader-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. northbees/autotrader-api

ActiveLibrary[API Development](/categories/api)

northbees/autotrader-api
========================

A Laravel SDK for the Autotrader API - vehicles, valuations, stock management, finance, deals, and more.

v1.1.2(2mo ago)16MITPHPPHP ^8.4CI passing

Since Mar 4Pushed 2mo ago2 watchersCompare

[ Source](https://github.com/NorthBees/autotrader-api)[ Packagist](https://packagist.org/packages/northbees/autotrader-api)[ Docs](https://github.com/northbees/autotrader-api)[ RSS](/packages/northbees-autotrader-api/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (13)Versions (14)Used By (0)

NorthBees Autotrader API
========================

[](#northbees-autotrader-api)

[![Latest Version on Packagist](https://camo.githubusercontent.com/73ee0b403053b811641f88a02b8349aaf00f36a471bb08dbceb5a42d73920a77/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6e6f727468626565732f6175746f7472616465722d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/northbees/autotrader-api)[![Tests](https://github.com/northbees/autotrader-api/actions/workflows/tests.yml/badge.svg)](https://github.com/northbees/autotrader-api/actions/workflows/tests.yml)[![License](https://camo.githubusercontent.com/096cfdc135bd9a7cdb781eed7085eea27d34889d60b4bde7b81f65685981ae96/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6e6f727468626565732f6175746f7472616465722d6170692e7376673f7374796c653d666c61742d737175617265)](LICENSE.md)[![PHP Version](https://camo.githubusercontent.com/f62942ea1b685f6fd27f54ab02671d305baca5170ef195cac82f8b9b2892c041/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6e6f727468626565732f6175746f7472616465722d6170692e7376673f7374796c653d666c61742d737175617265)](composer.json)

A Laravel SDK for the [Autotrader API](https://developers.autotrader.co.uk/api) - vehicles, valuations, stock management, finance, deals, and more.

Requirements
------------

[](#requirements)

- PHP 8.4+
- Laravel 11 or 12

Installation
------------

[](#installation)

```
composer require northbees/autotrader-api
```

The package uses Laravel's auto-discovery, so the service provider will be registered automatically.

Publish the configuration file:

```
php artisan vendor:publish --tag=autotrader.config
```

Configuration
-------------

[](#configuration)

Add the following to your `.env` file:

```
AUTOTRADER_ENVIRONMENT=sandbox
AUTOTRADER_KEY=your-api-key
AUTOTRADER_SECRET=your-api-secret
```

See [.env.example](.env.example) for all available options.

Authentication is handled automatically when any API call is made. The token will be cached.

Usage
-----

[](#usage)

The package is a lightweight wrapper around the Autotrader API.

### Vehicle Request

[](#vehicle-request)

```
// Basic Request
$vehicle = app(AutotraderApi::class)->getVehicle($advertiserId, $vrm);

// Request with mileage
$vehicle = app(AutotraderApi::class)->getVehicle($advertiserId, $vrm, $mileage);

// Request with mileage and additional data
$vehicle = app(AutotraderApi::class)->getVehicle($advertiserId, $vrm, $mileage, [
    'features' => true,
    'motTests' => false,
    'history' => false,
    'fullVehicleCheck' => false,
    'valuations' => false,
    'vehicleMetrics' => false,
    'factoryCodes' => true,
]);
```

### Search Request

[](#search-request)

```
// Basic search
$results = app(AutotraderApi::class)->searchVehicles($advertiserId);

// Search with criteria
$results = app(AutotraderApi::class)->searchVehicles($advertiserId, [
    'make' => 'BMW',
    'model' => 'X5',
    'priceFrom' => 10000,
    'priceTo' => 50000,
    'factoryCodes' => ['FC123', 'FC456'],
    'wheelbaseMM' => 2975,
]);

// Search with monthly price option (replaces deprecated financeOption)
$results = app(AutotraderApi::class)->searchVehicles($advertiserId, [
    'make' => 'BMW',
    'monthlyPriceOption' => [
        'mileage' => 10000,
        'deposit' => 1000,
        'term' => 48,
    ],
]);

// Search with additional options including financeOffers (headlineOffer)
$results = app(AutotraderApi::class)->searchVehicles($advertiserId, $searchCriteria, [
    'features' => true,
    'factoryCodes' => true,
    'wheelbaseMM' => true,
    'financeOffers' => true, // Includes headlineOffer in response
]);
```

**Search API response notes:**

- `financeOffers.headlineOffer`: Available when `financeOffers` option is enabled (Aug 2025)
- `vehicle.origin`: Indicates if the vehicle is UK or Non UK specification (Oct 2025)
- `rarityRating`, `valueRating`: Autotrader intelligence ratings for vehicle features (Aug 2025)
- `financeOption` search parameter is **deprecated** - use `monthlyPriceOption` instead (Feb 2026)

### Valuation Request

[](#valuation-request)

```
// To request a valuation, first complete a vehicle request
$vehicle = app(AutotraderApi::class)->getVehicle($advertiserId, $vrm);

// Then do a valuation lookup
$valuation = app(AutotraderApi::class)->getValuation($advertiserId, $vehicle->derivativeId, $mileage, $vehicle->firstRegistrationDate);

//You can also pass additional data to adjust your valuation
$valuation = app(AutotraderApi::class)->getValuation($advertiserId, $vehicle->derivativeId, $mileage, $vehicle->firstRegistrationDate, [
        'totalPrice' => null,
        'features' => null,
        'conditionRating' => null,
        'priceIndicatorRatingBands' => true,
    ]));
```

### Future and Historic Valuation Requests

[](#future-and-historic-valuation-requests)

```
$historic = app(AutotraderApi::class)->getHistoricValuation($advertiserId, $vehicle->derivativeId, $historicOdometerReadingMiles, $firstRegistrationDate,  $historicValuationDate);
$future = app(AutotraderApi::class)->getFutureValuation($advertiserId, $vehicle->derivativeId, $futureOdometerReadingMiles, $firstRegistrationDate,  $futureValuationDate);
```

### Taxonomy Requests

[](#taxonomy-requests)

```
$taxonomy = app(AutotraderApi::class)->getVehicleTypes($advertiserId);

/// Production status is optional, and can be Current, Discontinued or Future
$taxonomy = app(AutotraderApi::class)->getMakes($advertiserId, $vehicleType, $productionStatus);
$taxonomy = app(AutotraderApi::class)->getModels($advertiserId, $makeId, $model, $productionStatus);
$taxonomy = app(AutotraderApi::class)->getGenerations($advertiserId, $modelId, $productionStatus);
$taxonomy = app(AutotraderApi::class)->getDerivatives($advertiserId, $generationId, $productionStatus);

// Search by OEM model code (e.g. Volvo derivatives) - requires generationId
$taxonomy = app(AutotraderApi::class)->getDerivatives($advertiserId, $generationId, null, $oemModelCode);

//Effective date is optional
$taxonomy = app(AutotraderApi::class)->getFeatures($advertiserId, $derivativeId, $effectiveDate, $productionStatus, [
    'factoryCodes' => true,
]);
$taxonomy = app(AutotraderApi::class)->getPrices($advertiserId, $derivativeId, $effectiveDate, $productionStatus);
$taxonomy = app(AutotraderApi::class)->getTechnicalData($advertiserId, $derivativeId);

// Facets are: fuelTypes, transmissionTypes, bodyTypes, trims, doors, drivetrains, wheelbaseTypes, cabTypes, axleConfigurations, badgeEngineSizes, styles, subStyles, endLayouts, bedroomLayouts
$taxonomy = app(AutotraderApi::class)->getFacets( $advertiserId,  $facet,  $generationId,  $productionStatus);
```

**Taxonomy API response notes:**

- `rarityRating`, `valueRating`: Autotrader intelligence ratings for vehicle features (Aug 2025)
- Manufacturer warranty details (paintwork, standard, corrosion, battery) available in Taxonomy and Vehicles APIs (Oct 2025)

### Image Upload

[](#image-upload)

```
$imageId = app(AutotraderApi::class)->addImage($advertiserId, $filePath);
```

### Vehicle Metrics

[](#vehicle-metrics)

```
$valuation = app(AutotraderApi::class)->getMetrics($advertiserId, $vehicle->derivativeId, $mileage, $vehicle->firstRegistrationDate);

// With vatStatus for commercial vehicle No VAT valuations
$valuation = app(AutotraderApi::class)->getVehicleMetrics($advertiserId, $derivativeId, $mileage, $firstRegistrationDate, [
    'vatStatus' => 'NO_VAT',
]);
```

### Finance Requests

[](#finance-requests)

```
// Get finance options (quotes)
$financeOptions = app(AutotraderApi::class)->getFinanceOptions($advertiserId, $vehicleData);

// Submit finance application (note: only months fields are used, not years)
// Use financeTerms.productType instead of deprecated financeTerms.product
// Use applicant.replacingExistingLoan instead of deprecated affordability.replacingExistingLoan
// Use applicant.lastName instead of deprecated applicant.surname
$application = app(AutotraderApi::class)->submitFinanceApplication($advertiserId, [
    'monthsAtBank' => 40, // Previously would be yearsAtBank: 3, monthsAtBank: 4
    'monthsAtEmployer' => 36,
    'monthsAtAddress' => 48,
    'financeTerms' => [
        'productType' => 'PCP', // Use productType, not deprecated product
    ],
    'applicant' => [
        'lastName' => 'Smith', // Use lastName, not deprecated surname
        'replacingExistingLoan' => true, // Use this, not deprecated affordability.replacingExistingLoan
        'monthlyRentOrMortgage' => ['amountGBP' => 800], // Use this, not deprecated monthlyRentOrMortgageGBP
        'monthlyChildcare' => ['amountGBP' => 200], // Use this, not deprecated monthlyChildCareGBP
    ],
    // ... other finance data
]);

// Update finance application
$updated = app(AutotraderApi::class)->updateFinanceApplication($advertiserId, $applicationId, $financeData);
```

**Finance API deprecation notes (Feb 2026):**

- `financeTerms.product` is deprecated - use `financeTerms.productType`
- `product` in quotes/proposals is deprecated - use `productType`
- `productName` added to quotes for lender specific product name
- `affordability.replacingExistingLoan` is deprecated - use `applicant.replacingExistingLoan`

**Finance API deprecation notes (Oct/Nov 2025):**

- `applicant.surname` is deprecated and removed - use `applicant.lastName`
- `applicant.monthlyRentOrMortgageGBP.amountGBP` is deprecated and removed - use `applicant.monthlyRentOrMortgage.amountGBP`
- `applicant.monthlyChildCareGBP.amountGBP` is deprecated and removed - use `applicant.monthlyChildcare.amountGBP`
- `questions` in quotes is deprecated and removed - use `quotesRequirements`
- `ineligibilityReasons` in quotes is deprecated and removed - use `quotesRequirements`
- `proposalRequirements` and `quotesRequirements` added to Quotes response

### Stock Requests

[](#stock-requests)

```
// Get stock list with new features
$stock = app(AutotraderApi::class)->getStockList($advertiserId, $filters, [
    'factoryCodes' => true,
    'priceIndicatorRatingBands' => true,
    'wheelbaseMM' => true,
]);

// Get real-time stock summary
$summary = app(AutotraderApi::class)->getStockSummary($advertiserId, $stockId);

// Update stock - mark as SOLD and unpublish tradeAdvert
$updated = app(AutotraderApi::class)->updateStock($advertiserId, [
    'metadata' => ['stockId' => $stockId, 'lifecycleState' => 'SOLD'],
    'adverts' => ['tradeAdvert' => ['status' => 'NOT_PUBLISHED']],
]);
```

**Stock API response notes:**

- `eligibleContractAllowances`, `allocatedContractAllowance`: Contract allowance information (Aug 2025)
- `vehicle.origin`: Indicates if the vehicle is UK or Non UK specification (Oct 2025)
- tradeAdvert can now be set to NOT\_PUBLISHED when updating stock lifecycle to SOLD (Feb 2026)

### Deals Requests

[](#deals-requests)

```
// Get all deals for an advertiser
$deals = app(AutotraderApi::class)->getDeals($advertiserId);

// Get deals with filters
$deals = app(AutotraderApi::class)->getDeals($advertiserId, [
    'page' => 1,
    'from' => '2023-05-05',
    'to' => '2023-05-07',
]);

// Get a specific deal
$deal = app(AutotraderApi::class)->getDeal($advertiserId, $dealId);

// Create a new deal (originated outside of Autotrader consumer journey)
$deal = app(AutotraderApi::class)->createDeal($advertiserId, [
    'stockId' => $stockId,
    // ... deal data
]);

// Complete a deal
$response = app(AutotraderApi::class)->completeDeal($advertiserId, $dealId);

// Cancel a deal with reason
$response = app(AutotraderApi::class)->cancelDeal($advertiserId, $dealId, 'Unaffordable', 'Customer cannot afford the deposit');

// Update a deal with custom data
$response = app(AutotraderApi::class)->updateDeal($advertiserId, $dealId, [
    'advertiserDealStatus' => 'Complete'
]);

// Remove deal components
$response = app(AutotraderApi::class)->removeDealPartExchange($advertiserId, $dealId);
$response = app(AutotraderApi::class)->removeDealFinanceApplication($advertiserId, $dealId);
```

**Deals API response notes:**

- `buyingSignals`: Consumer behaviour indicators including dealIntentScore, intent, localCustomer, advertSaved, preferences (Nov 2025)
- `reservation` object: Replaces deprecated `stock.reservationStatus` and `consumerReservationFeeStatus`. Includes status values Requested and Reserved (Jan 2026)
- `stock.reservationStatus` is **deprecated** - use `reservation` object instead (Jan 2026)
- `consumerReservationFeeStatus` is **deprecated** - use `reservation` object instead (Jan 2026)

### Messages Requests

[](#messages-requests)

```
// Get messages for a specific message ID
$messages = app(AutotraderApi::class)->getMessages($advertiserId, $messagesId);

// Mark messages as read
$response = app(AutotraderApi::class)->markMessagesAsRead($advertiserId, $messagesId);

// Send a new message for a new conversation
$response = app(AutotraderApi::class)->sendMessage($advertiserId, [
    'dealId' => '1a0e00aa-459b-162d-a23a-adcbb1110f04',
    'message' => 'Your message here (max 1500 characters)'
]);

// Send a message to an existing conversation
$response = app(AutotraderApi::class)->sendMessage($advertiserId, [
    'messagesId' => 'e00a1a0a-162d-459b-a23a-0f04adcbb111',
    'message' => 'Your reply message here'
]);
```

### Delivery Requests

[](#delivery-requests)

```
// Get delivery details
$delivery = app(AutotraderApi::class)->getDelivery($advertiserId, $deliveryId);
// Get call details
$calls = app(AutotraderApi::class)->getCalls($advertiserId, $callId);
```

### Integrations Requests

[](#integrations-requests)

```
// Get integrations for the current partner
$integrations = app(AutotraderApi::class)->getIntegrations();
```

**Integrations API notes:**

- Returns a view of what integrations a partner has access to (API, Datafeeds, Exports)
- For API integrations, shows all capabilities the integration has access to
- Introduced Nov 2025

### Advertisers Requests

[](#advertisers-requests)

```
// Get advertisers
$advertisers = app(AutotraderApi::class)->getAdvertisers();
```

**Advertisers API response notes:**

- `capabilities` object: Lists atConnect capabilities a partner's application is permitted to use on behalf of an advertiser (Oct 2025)

### Valuation API Response Notes

[](#valuation-api-response-notes)

- `amountNoVatGBP` fields for retail, trade, and part exchange valuations are available for vehicles not requiring VAT (Aug 2025)
- Also available in Historic Valuations and Vehicles APIs

### Vehicle API Response Notes

[](#vehicle-api-response-notes)

- `rarityRating`, `valueRating`: Autotrader intelligence ratings for vehicle features (Aug 2025)
- Manufacturer warranty details (paintwork, standard, corrosion, battery) provided by manufacturer for brand new vehicles (Oct 2025)

Testing
-------

[](#testing)

```
composer test
```

Code Style
----------

[](#code-style)

This package uses [Laravel Pint](https://laravel.com/docs/pint) for code style:

```
composer lint
```

Static Analysis
---------------

[](#static-analysis)

[PHPStan](https://phpstan.org/) with [Larastan](https://github.com/larastan/larastan) is used for static analysis:

```
composer analyse
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](SECURITY.md) on how to report security vulnerabilities.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

44

—

FairBetter than 92% of packages

Maintenance85

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community12

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 66.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Total

5

Last Release

60d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/42f50b107f29b6bdd4396c486e0c0797be32a23c8de70140e048b2756d6f75b2?d=identicon)[sdsmith1981](/maintainers/sdsmith1981)

---

Top Contributors

[![sdsmith1981](https://avatars.githubusercontent.com/u/3822955?v=4)](https://github.com/sdsmith1981 "sdsmith1981 (58 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (21 commits)")[![LiamThursfield](https://avatars.githubusercontent.com/u/9251736?v=4)](https://github.com/LiamThursfield "LiamThursfield (7 commits)")[![Harrk](https://avatars.githubusercontent.com/u/2372590?v=4)](https://github.com/Harrk "Harrk (1 commits)")

---

Tags

apilaravelsdkfinancetaxonomydealsstockvehiclesautotradervaluations

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/northbees-autotrader-api/health.svg)

```
[![Health](https://phpackages.com/badges/northbees-autotrader-api/health.svg)](https://phpackages.com/packages/northbees-autotrader-api)
```

###  Alternatives

[resend/resend-laravel

Resend for Laravel

1191.4M6](/packages/resend-resend-laravel)[orzcc/taobao-top-client

Taobao top client(SDK) for laravel

11125.9k](/packages/orzcc-taobao-top-client)[missael-anda/laravel-whatsapp

A Whatsapp Business Cloud API wrapper for Laravel.

677.5k](/packages/missael-anda-laravel-whatsapp)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)