Vehicles API v2024-11-01 Use Case Guide

How to use the Vehicles API.

API Version: 2024-11-01

What is the Vehicles API?

With the Selling Partner API for Vehicles (Vehicles API), you can retrieve information about vehicles, including their unique identifiers. You can use this information to provide compatibility information for listed ASINs with the Listings API.

Items that require vehicle fitment information require a list of vehicle KTYPEs. This API provides a list of vehicles and their KTYPE, which you can use to independently map each item in your catalog to a list of KTYPEs. This mapping can then be provided to Amazon using the Listings API.

What is in this guide?

This guide describes how to:

Use the Vehicles API to get the latest list of vehicles.
Update the fitment information for an ASIN using the Listings API.

Terminology

ASIN: The Amazon Standard Identification Number that identifies an item in the Amazon catalog.
KTYPE: A numeric identifier associated with a vehicle definition (brand, model, type, year) and used by various brands to link their products.

Tutorial 1: Provide fitment information on ASINs

Provide compatibility information for items in your catalog.

Prerequisites

To complete this tutorial, you must have:

Authorization from the selling partner for whom you are making calls. Refer to the Authorizing Selling Partner API applications for more information.
Approval for the Product Listing role in your developer profile.
The Product Listing role selected in the App registration page for your application.

Step 1. Retrieve a list of vehicles and their KTYPEs

To get a list of vehicles, call the getVehicles operation.

Query parameters

Name	Description	Required
`marketplaceId`	An identifier for the marketplace in which the resource operates. To find the ID for a marketplace, refer to Marketplace IDs. Type: string	Yes
`vehicleType`	The type of vehicle. Possible values are `CAR` and `MOTORBIKE`. Type: enum (`VehicleType`)	Yes
`pageToken`	A token that you can use to retrieve the next page or previous page of results. The response includes `pagination` when the number of results exceeds the page size. To get the next page of results, call the operation with the `nextToken` and include the same arguments as the call that produced the token. To get a complete list, call this operation until there is no `nextToken` in the response. Note that this operation can return empty pages. Type: string	No
`updatedAfter`	Include this field to only retrieve vehicles that have been modified or added to Amazon's catalog after the date that you provide. Must be in ISO 8601 date-time format. Type: string	No

Request example

GET https://sellingpartnerapi-eu.amazon.com/catalog/2024-11-01/automotive/vehicles?marketplaceId=A1F83G8C2ARO7P&updatedAfter=2024-11-01T01:00:00+01:00&vehicleType=CAR

Response

A successful response includes the following properties:

Name	Description
`pagination`	The `nextToken` and `previousToken` values required to retrieve the next or previous page of results, if available. Type: `Pagination`
`vehicles`	A list of vehicles from Amazon's catalog. Type: < `Vehicle` > array

Response example

{
  "pagination": {
    "nextToken": "AQICAHhviiXpt-KG7DcOWDoXPW4_B4xAKk9r-8oi43dEh_cI4QF"
  },
  "vehicles": [
    {
      "bodyStyle": "MPV",
      "driveType": "Front-Wheel Drive",
      "energy": "Petrol/Liquified Petroleum Gas (LPG)",
      "engineOutput": [
        {
          "unit": "KILOWATT",
          "value": 61.0
        },
        {
          "unit": "HORSEPOWER",
          "value": 83.0
        }
      ],
      "identifiers": [
        {
          "standard": "KTYPE",
          "value": "100408"
        }
      ],
      "lastProcessedDate": "2024-11-01T01:00:00+01:00",
      "make": "Dacia",
      "manufacturingStartDate": {
        "month": 11,
        "year": 2013
      },
      "manufacturingStopDate": {
        "month": 12,
        "year": 2015
      },
      "model": "Dokker",
      "status": "ACTIVE",
      "variantName": "1.6 LPG"
    },
    {
      "bodyStyle": "Closed Off-Road Vehicle",
      "driveType": "All-wheel Drive",
      "energy": "Petrol",
      "engineOutput": [
        {
          "unit": "KILOWATT",
          "value": 100.0
        },
        {
          "unit": "HORSEPOWER",
          "value": 136.0
        }
      ],
      "identifiers": [
        {
          "standard": "KTYPE",
          "value": "10232"
        }
      ],
      "lastProcessedDate": "2024-11-01T01:00:00+01:00",
      "make": "Vauxhall",
      "manufacturingStartDate": {
        "month": 10,
        "year": 1998
      },
      "manufacturingStopDate": {
        "month": 10,
        "year": 2004
      },
      "model": "Frontera",
      "status": "ACTIVE",
      "variantName": "2.2 I"
    },
    {
      "bodyStyle": "Closed Off-Road Vehicle",
      "driveType": "All-wheel Drive",
      "energy": "Petrol",
      "engineOutput": [
        {
          "unit": "KILOWATT",
          "value": 151.0
        },
        {
          "unit": "HORSEPOWER",
          "value": 205.0
        }
      ],
      "identifiers": [
        {
          "standard": "KTYPE",
          "value": "10233"
        }
      ],
      "lastProcessedDate": "2024-11-01T01:00:00+01:00",
      "make": "Vauxhall",
      "manufacturingStartDate": {
        "month": 10,
        "year": 1998
      },
      "manufacturingStopDate": {
        "month": 10,
        "year": 2004
      },
      "model": "Frontera",
      "status": "ACTIVE",
      "variantName": "3.2 I"
    },
    {
      "bodyStyle": "Closed Off-Road Vehicle",
      "driveType": "All-wheel Drive",
      "energy": "Diesel",
      "engineOutput": [
        {
          "unit": "KILOWATT",
          "value": 85.0
        },
        {
          "unit": "HORSEPOWER",
          "value": 116.0
        }
      ],
      "identifiers": [
        {
          "standard": "KTYPE",
          "value": "10234"
        }
      ],
      "lastProcessedDate": "2024-11-01T01:00:00+01:00",
      "make": "Vauxhall",
      "manufacturingStartDate": {
        "month": 10,
        "year": 1998
      },
      "manufacturingStopDate": {
        "month": 9,
        "year": 2004
      },
      "model": "Frontera",
      "status": "ACTIVE",
      "variantName": "2.2 DTI"
    }
  ]
}

Step 2. Map your items to KTYPEs

Use the response from the previous step to select vehicles that your items fit. For each item, record the KTYPE of the vehicles that fit it. You provide this list of KTYPEs in the next step.

Step 3. Update the fitment with the Listings API

To update fitment information on an ASIN, call the patchListingsItem operation. The patches parameter in the request body should have the path equal to /attributes/vehicle_fitment and contain the list of KTYPEs in value.

Path parameters

Name	Description	Required
`sellerId`	A selling partner identifier, such as a merchant account or vendor code. Type: string	Yes
`sku`	A selling partner provided identifier for an Amazon listing. Type: string	Yes

Query parameters

Name	Description	Required
`marketplaceIds`	A comma-delimited list of Amazon marketplace identifiers for the request. Type: array	Yes
`includedData`	A comma-delimited list of data sets to include in the response. Type: < enum (`IncludedData`) > array	No
`mode`	The mode of operation for the request. Type: enum (`Mode`)	No
`issueLocale`	A locale for localization of issues. When not provided, the default language code of the first marketplace is used. Type: string	No

Body parameters

Name	Description	Required
`productType`	The Amazon product type of the listings item. Type: string	Yes
`patches`	One or more JSON Patch operations to perform on the listings item. Type: < `PatchOperation` > array	Yes

Request example

PATCH https://sellingpartnerapi-eu.amazon.com/listings/2021-08-01/items/XXXXXXXXXX/SKU_XXXXXX?includedData=issues&marketplaceIds=A1PA6795UKMFR9
{
  "productType": "AUTO_OIL",
  "patches": [
    {
      "op": "replace",
      "path": "/attributes/vehicle_fitment",
      "value": [
        {
          "standard": [
            {
              "value": "ktype",
              "language_tag": "de_DE"
            }
          ],
          "code": [
            {
              "value": "10232, 10234, 10233",
              "language_tag": "de_DE"
            }
          ],
          "note": [
            {
              "value": "{\"10232,10234\":[[[\"Fahrwerk\",\"für Fahrzeuge mit M-Technik\"]]],\"10233\":[[[\"Fahrwerk\",\"für Fahrzeuge mit M-Technik\"],[\"Motorcode\",\"N47 D20 C\"]]]}",
              "language_tag": "de_DE"
            }
          ],
          "marketplace_id": "A1PA6795UKMFR9"
        }
      ]
    }
  ]
}

Response

A successful response includes the following properties:

Name	Description
`sku`	A selling partner provided identifier for an Amazon listing. Type: string
`status`	The status of the listings item submission. Type: enum (`Status`)
`submissionId`	The unique identifier of the listings item submission. Type: string
`issues`	Listings item issues related to the listings item submission. Type: < `Issue` > array
`identifiers`	Identity attributes associated with the item in the Amazon catalog, such as the ASIN. Type: `ItemIdentifiers`

Response example

{
  "sku": "SKU-XXXX-XXXX",
  "status": "ACCEPTED",
  "submissionId": "xxxxxxxxxxxxxxxxx",
  "issues": []
}

❗️
Terms of use
When downloading and using the data provided by this API, the terms of use found here apply and are accepted by users.

Updated about 7 hours ago

What is the Vehicles API?

What is in this guide?

Terminology

Tutorial 1: Provide fitment information on ASINs

Prerequisites

Step 1. Retrieve a list of vehicles and their KTYPEs

Query parameters

Request example

Response

Response example

Step 2. Map your items to KTYPEs

Step 3. Update the fitment with the Listings API

Path parameters

Query parameters

Body parameters

Request example

Response

Response example

❗️Terms of use

❗️
Terms of use