General Concepts

INCENTIVES API

Overview.

The incentives API provided access to the national, regional and local incentives available for each OEM.

API Uses

  • Get a list of all incentives
  • Get Incentive information by incentive ID

Available Resources

Resource Name Description
Incentive Information This is where you can get all the information for an incentive.

Incentive Information

This is where you can get dealer's incentives information.

Endpoints

  • Get all incentives
  • Get incentive by incentiveId

URL

To make a call, make an HTTPS get request
https://api.dealer.com/incentives?api_key={api_key}
https://api.dealer.com/incentives/id/{incentiveId}?api_key={api_key}

Parameters

For /incentives

Parameter Description Possible Values Default Value Type In Required
select Select the properties will get returned by the query applicableModel ,bodyStyle ,category ,condition ,conditional ,content ,countryCode ,creatorAccountId ,data ,defaultLanguage ,disclaimer ,displayAds ,effectiveDate ,expirationDate ,featured ,filterEffectiveTimestampInUTC ,filterExpirationTimestampInUTC ,globalVehicleTrimIds ,globallyVisible ,imageUrl ,incentiveCreatedDate ,incentiveType ,languageCodes ,make ,mappedByInventory ,model ,offerDetails ,priority ,shortTitle ,stateDisclaimer ,tcdAds ,title ,trim ,trims ,typeDisclaimer ,vehicleTrims ,year String array Query No
start Initial position where the pagination will start Integer Query No
size size of each page Integer Query No
uniqueId Unique identifier of an incentive, it will unique represent a combination of incentiveId and Account String Query No
creatorAccountId If the incentive was create as part of one batch feed this value will match with the feed create the incentive String Query No
incentiveId ID of the incentive, this could be in many accounts String Query No
accountId ID of the account String Query No
incentiveType Filter by incentive type String Query No
defaultLanguage Default language String Query No
countryCode Country code String Query No
year Incentive year Integer Query No
make Incentive make String Query No
model Incentive model String Query No
For /incentives/id/{uniqueId}
Parameter Description Possible Values Default Value Type In Required
select Select the properties will get returned by the query applicableModel ,bodyStyle ,category ,condition ,conditional ,content ,countryCode ,creatorAccountId ,data ,defaultLanguage ,disclaimer ,displayAds ,effectiveDate ,expirationDate ,featured ,filterEffectiveTimestampInUTC ,filterExpirationTimestampInUTC ,globalVehicleTrimIds ,globallyVisible ,imageUrl ,incentiveCreatedDate ,incentiveType ,languageCodes ,make ,mappedByInventory ,model ,offerDetails ,priority ,shortTitle ,stateDisclaimer ,tcdAds ,title ,trim ,trims ,typeDisclaimer ,vehicleTrims ,year String array Query No
uniqueId Unique identifier of an incentive, it will unique represent a combination of incentiveId and Account String path Yes

Response

Incentive Base

Description

Represents the basic details for an incentive.

Name Type Description
uniqueID String The unique ID for the incentive which is formatted accountID_incentiveID.
created Timestamp The date and time that the incentive was created.
lastUpdate Timestamp The date and time the incentive was last updated.

Incentive Data Content

Description

Represents the partial details for an incentive.

Name Type Description
incentiveId String The unique ID for the incentive.
accountId String The unique ID for the account.
creatorAccountId String The incentive data source. Can be a third party provider or an internal accountId.
incentiveType String The type of incentive (Cash, Lease, Finance, etc.)
incentiveData IncentiveData Describes the different details of a cash, lease or finance incentive.
defaultLanguage String The default language the incentive is described in.
countryCode String The country where the incentive is applicable.
applicableYear Integer The model year of the vehicles that the incentive is applicable to.
applicableMake String The OEM for the vehicles that the incentive is applicable to.
applicableModel String The OEM model(s) that the incentive is applicable to.
thirdPartyId String The incentive data provider.
languageCodes Array The list of languages the incentive is described in.
generateTcdAds Boolean Flag for generating pay-per-click ads with the incentive details.
generateDisplayAds Boolean Flag for generating display ads with the incentive details.
mappedByInventory Boolean Internal to DDC.
featured Boolean Flag for featuring the incentive in the DDC website featured incentive widget.
effectiveDate Date The date that the incentive should be effective.
expirationDate Date The date that the incentive should be expired.
filterEffectiveTimestampInUTC Timestamp The timestamp that the incentive should be effective taking into consideration the account timezone.
filterExpirationTimestampInUTC Timestamp The timestamp that the incentive should be expire taking into consideration the account timezone.
conditional Boolean Flag for if the incentive is conditional.
conditionalCategory String The category that the incentive would fall under if it were conditional (Conquest, Loyalty, etc.)
i18NTitle Label Array List of localized incentive titles.
i18NOfferDetails Label Array Localized incentive details.
i18NContent Label Array Localized incentive content.
i18NDisclaimer Label Array Localized incentive disclaimer.
i18NImageUrl Label Array Image associate to the incentive, only provided for few OEMs
priority Integer Incentive display priority
globallyVisible Boolean Identify if the incentive should be globally visible on the system.
incentiveCreatedDate Timestamp The date and time the incentive was added to the DDC system.
applicableCondition String The vehicle condition type (New, Used or Certified) that the incentive is applicable for.
i18NApplicableModel Label Array The localized OEM model(s) that the incentive is applicable for.
i18NApplicableBodyStyle Label Array The localized body style(s) of the vehicles that the incentive is applicable to.

Incentive Data

Description

Describes the details of a cash, finance or lease incentive. The data returned will vary depending on the incentive type.

Fields for "CASH" Incentives
Name Type Description
_type String The incentive type (cash, finance or lease).
cashOption Double The total cash amount for the incentive.
lenderName String Name of the lender for the incentive.
Fields for "FINANCE" Incentives
Name Type Description
_type String The incentive type (cash, finance or lease).
cashOption Double The total cash amount for the incentive.
lenderName String Name of the lender for the incentive.
bestAprTerm Array The term with the best rate.
bestAprTerm: term Integer The term length in months.
bestAprTerm: value Integer The APR for the length of the term.
aprTerms Array List of available terms and rates.
aprTerms: term Integer The terms for the available rates.
aprTerms: value Double The APR's for the length of the terms.
Fields for "LEASE" Incentives
Name Type Description
_type String The incentive type (cash, finance or lease).
msrp Double The MSRP used to calculate the lease payment.
cashDue Double The cash amount due at signing.
aprTerms Array List of available terms and rates.
aprTerms: term Integer The terms for the available rates.
aprTerms: mapToCustom Integer Internal to DDC
aprTerms: value Double The APR's for the length of the terms.
monthlyPayment Double The monthly payment for the term of the lease.
mileageAllowance Integer The number of miles allowed to drive each year for the term of the lease.
purchaseOptionPrice Double The purchase price of the vehicle at lease-end.
capitalizationCost Double The total amount that is being financed for the term of the lease.

globalVehicleTrims

Description

Represents the global vehicle (GV) trims that the incentive is applicable to. Global vehicle is the internal DDC catalog data language. It is a modified version of AutoData catalog data.

Name Type Description
globalVehicleId String The AutoData catalog vehicle ID.
globalVehicleTrimIds Array/String The list of global vehicle trim ID's that the incentive is applicable to.

trims

Description

Represents a basic description for the vehicles that the incentive is applicable to.

Name Type Description
year Integer The model year of the vehicles that the incentive is applicable to.
make String The OEM for the vehicles that the incentive is applicable to.
model String The OEM model that the incentive is applicable to.
trim String The subset(s) of a model that the incentive is applicable to.
bodyStyle String The classification of vehicle that the incentive is applicable to.
globalVehicleTrimIds Array/String The list of global vehicle trim ID's that the incentive is applicable to.

Label Array

Description

Describes the details of a cash, finance or lease incentive. The data returned will vary depending on the incentive type.

Name Type Description
values String List of localized labels for all available languages.
value String The label for the 'defaultLanguage'

Links

Description

Represents a basic description for the vehicles that the incentive is applicable to.

Name Type Description
self String Self link to the entity
account String Link to account endpoint. Need to have access to Account API.

Response Format

/incentives/id/{uniqueId} 

                   {
  "@type": "string",
  "account": {
    "@type": "string",
    "accountId": "string",
    "links": [
      {
        "deprecation": "string",
        "href": "string",
        "hreflang": "string",
        "media": "string",
        "rel": "string",
        "templated": true,
        "title": "string",
        "type": "string"
      }
    ]
  },
  "applicableModel": {},
  "bodyStyle": {},
  "category": "string",
  "condition": "string",
  "conditional": true,
  "content": {},
  "countryCode": "string",
  "creatorAccountId": "string",
  "defaultLanguage": "string",
  "disclaimer": {},
  "displayAds": true,
  "effectiveDate": "2018-07-02T15:34:30.711Z",
  "expirationDate": "2018-07-02T15:34:30.711Z",
  "featured": true,
  "filterEffectiveTimestampInUTC": {
    "date": 0,
    "day": 0,
    "hours": 0,
    "minutes": 0,
    "month": 0,
    "nanos": 0,
    "seconds": 0,
    "time": 0,
    "timezoneOffset": 0,
    "year": 0
  },
  "filterExpirationTimestampInUTC": {
    "date": 0,
    "day": 0,
    "hours": 0,
    "minutes": 0,
    "month": 0,
    "nanos": 0,
    "seconds": 0,
    "time": 0,
    "timezoneOffset": 0,
    "year": 0
  },
  "globalVehicleTrimIds": [
    "string"
  ],
  "globallyVisible": true,
  "imageUrl": {},
  "incentiveCreatedDate": "2018-07-02T15:34:30.711Z",
  "incentiveId": "string",
  "languageCodes": [
    "string"
  ],
  "links": [
    {
      "deprecation": "string",
      "href": "string",
      "hreflang": "string",
      "media": "string",
      "rel": "string",
      "templated": true,
      "title": "string",
      "type": "string"
    }
  ],
  "make": "string",
  "mappedByInventory": true,
  "model": "string",
  "offerDetails": {},
  "priority": 0,
  "shortTitle": {},
  "specific": {},
  "stateDisclaimer": {},
  "tcdAds": true,
  "thirdPartyId": "string",
  "title": {},
  "trim": {},
  "trims": [
    {
      "bodyStyle": "string",
      "globalVehicleTrimIds": [
        "string"
      ],
      "make": "string",
      "model": "string",
      "trim": "string",
      "year": 0
    }
  ],
  "type": "string",
  "typeDisclaimer": {},
  "uniqueId": "string",
  "vehicleTrims": [
    {
      "vehicleId": "string",
      "vehicleTrimIds": [
        "string"
      ]
    }
  ],
  "year": 0
}
/incentives/search/ 

      [
  {
    "@type": "string",
    "account": {
      "@type": "string",
      "accountId": "string",
      "links": [
        {
          "deprecation": "string",
          "href": "string",
          "hreflang": "string",
          "media": "string",
          "rel": "string",
          "templated": true,
          "title": "string",
          "type": "string"
        }
      ]
    },
    "applicableModel": {},
    "bodyStyle": {},
    "category": "string",
    "condition": "string",
    "conditional": true,
    "content": {},
    "countryCode": "string",
    "creatorAccountId": "string",
    "defaultLanguage": "string",
    "disclaimer": {},
    "displayAds": true,
    "effectiveDate": "2018-07-02T15:36:40.883Z",
    "expirationDate": "2018-07-02T15:36:40.883Z",
    "featured": true,
    "filterEffectiveTimestampInUTC": {
      "date": 0,
      "day": 0,
      "hours": 0,
      "minutes": 0,
      "month": 0,
      "nanos": 0,
      "seconds": 0,
      "time": 0,
      "timezoneOffset": 0,
      "year": 0
    },
    "filterExpirationTimestampInUTC": {
      "date": 0,
      "day": 0,
      "hours": 0,
      "minutes": 0,
      "month": 0,
      "nanos": 0,
      "seconds": 0,
      "time": 0,
      "timezoneOffset": 0,
      "year": 0
    },
    "globalVehicleTrimIds": [
      "string"
    ],
    "globallyVisible": true,
    "imageUrl": {},
    "incentiveCreatedDate": "2018-07-02T15:36:40.883Z",
    "incentiveId": "string",
    "languageCodes": [
      "string"
    ],
    "links": [
      {
        "deprecation": "string",
        "href": "string",
        "hreflang": "string",
        "media": "string",
        "rel": "string",
        "templated": true,
        "title": "string",
        "type": "string"
      }
    ],
    "make": "string",
    "mappedByInventory": true,
    "model": "string",
    "offerDetails": {},
    "priority": 0,
    "shortTitle": {},
    "specific": {},
    "stateDisclaimer": {},
    "tcdAds": true,
    "thirdPartyId": "string",
    "title": {},
    "trim": {},
    "trims": [
      {
        "bodyStyle": "string",
        "globalVehicleTrimIds": [
          "string"
        ],
        "make": "string",
        "model": "string",
        "trim": "string",
        "year": 0
      }
    ],
    "type": "string",
    "typeDisclaimer": {},
    "uniqueId": "string",
    "vehicleTrims": [
      {
        "vehicleId": "string",
        "vehicleTrimIds": [
          "string"
        ]
      }
    ],
    "year": 0
  }
]