Tire Retail & Service Integration Manual
Developer guidance for integrating DecisioQ tire decisions with POS, fitment, inventory, appointment scheduling, service bays, warranty, fleet accounts, suppliers, and digital retail systems.The Tire Retail & Service sector in the DecisioQ Decision Catalog is identified by AUTO-TIRE. It covers tire recommendation, fitment, inventory forecasting, customer service, warranty, commercial fleet service, service bay capacity, digital retail, supplier, inspection, and business strategy decisions.
DecisioQ integrations should load sector, category, decision, Decision Preparation Model, and scenario metadata from the Decision Catalog. Do not hard-code old template names, static decision lists, or legacy request models.
Recommended first deployment: start with a workflow that service advisors or digital retail teams already review manually, such as tire recommendation, appointment prioritization, warranty eligibility, fleet tire replacement, supplier fulfillment, or inventory replenishment.
Tire Retail & Service client applications should use the same discovery flow as the Business Decision Studio:
- Load
GET /decisioncatalogthrough the approved server-side Decision Catalog gateway. - Populate Sector from
catalog.sectors[]and selectAUTO-TIREfor Tire Retail & Service. - Populate Category from
selectedSector.categories[]. Example categories include Commercial Fleet Tire Services, Customer Services, Digital Retail & Innovation, Fleet Tire Intelligence, Inventory Optimization & Forecasting, Service Operations, Supplier Fulfillment, and Business Strategy. - Populate Decision from
selectedCategory.decisions[]when available, or call/decisioncatalog/sectors/{sectorCode}/categories/{categoryCode}/decisions. - Display Decision Name only in the dropdown while keeping
decisionIdas the option value. - Load full decision detail from
/decisioncatalog/decisions/{decisionId}before rendering Guided Data Collection.
Decision detail is the source of truth for criterion names, data guidance, scale, direction, profile options, scenarios, and overview metadata.
For regional deployments, keep DecisioQ technical identifiers stable and localize only user-facing labels and guidance. Unless the selected endpoint and decision schema explicitly support unit-qualified input, convert mileage, distance, pressure, temperature, mass, volume, speed, fuel consumption, and other measurements to the required canonical units before submission. Do not infer units or currency from locale.
| Use Case | Primary Users | Typical Inputs |
|---|---|---|
| Tire recommendation and fitment | Service advisors, digital retail, call center, fleet account teams | Vehicle fitment, tire size, driving conditions, season, budget, inventory, warranty, brand preference. |
| Appointment and service bay prioritization | Store managers, service advisors, scheduling systems | Customer urgency, tire availability, bay capacity, technician skill, service duration, fleet priority. |
| Warranty and goodwill handling | Customer service, warranty administrators, store managers | Purchase age, tread depth, damage type, road hazard coverage, evidence quality, customer value. |
| Supplier and fulfillment selection | Counter staff, purchasing, eCommerce operations | Local stock, warehouse stock, supplier availability, landed cost, lead time, rebate, service promise. |
| Inventory replenishment and forecasting | Inventory planners, store managers, warehouse teams | Sales velocity, seasonality, on-hand quantity, stockout risk, margin, forecast, transfer cost. |
| Commercial fleet tire service | Fleet account managers, service operations | Fleet SLA, vehicle downtime risk, tire condition, route duty cycle, replacement urgency, contract terms. |
| Maintenance package recommendation | Service advisors, digital retail, customer retention teams | Alignment need, rotation status, TPMS state, inspection results, customer preference, service history. |
| Digital retail and business strategy | Operations leaders, product teams, store leadership | Business value, customer impact, implementation effort, data readiness, ROI, adoption risk. |
Tire integrations should map vehicle, tire, customer, inventory, supplier, appointment, service bay, inspection, warranty, and fleet account data into decision-specific Business Data. The selected decision detail defines which criteria are required and how each value should be measured.
| Business Data Source | Common Use | Integration Notes |
|---|---|---|
| VIN, vehicle ID, tire SKU, quote ID, repair order ID, appointment ID, fleet unit ID, or warranty claim ID | optionId and audit correlation. | Keep stable source-system IDs so recommendations can be traced to POS, eCommerce, fitment, shop, supplier, and warranty records. |
| Fitment and product catalog data | Tire recommendation, compatibility, substitute tire, digital retail guidance. | Separate confirmed fitment, size compatibility, speed/load rating, season type, and product attributes. |
| Inventory and supplier data | Fulfillment, replenishment, stockout response, transfer and purchase decisions. | Keep local stock, warehouse stock, supplier stock, lead time, landed cost, rebate, and transfer cost distinct. |
| Appointment and service operations data | Bay scheduling, fleet service priority, service package recommendation. | Refresh bay capacity, technician availability, tire availability, and expected service duration close to execution time. |
| Inspection and tire condition data | Replacement, rotation, alignment, warranty, road hazard, follow-up decisions. | Capture tread depth, wear pattern, damage evidence, pressure, TPMS state, and safety risk separately. |
| Customer and fleet account data | Recommendation, goodwill, service priority, fleet tire program decisions. | Protect customer data and distinguish customer value, contract SLA, urgency, and preference from technical tire criteria. |
| Financial and merchandising data | Pricing, package, promotion, replenishment, expansion decisions. | Use explicit currency and unit assumptions for margin, discount, rebate, service revenue, and inventory carrying cost. |
Do not invent criterion IDs. Use the canonical criteria returned by /decisioncatalog/decisions/{decisionId}, including criterion overview metadata, unit, direction, scale, and data guidance.
Production integrations should keep credentials and bearer tokens on trusted servers or server-side gateways. Browser pages should use same-origin proxy handlers or their own backend service.
- Trusted backend obtains a JWT token from
identity.vinquery.com. - Application loads catalog and decision detail metadata.
- User or system prepares Business Data for candidate tires, service slots, suppliers, warranty outcomes, inventory actions, fleet service options, or strategy investments.
- Call
POST /api/v1/validateto validate and prepare the decision input before execution. - Call
POST /api/v1/decideto return the authoritative Decision Result. - Display the recommendation, ranked alternatives, warnings, assumptions, and Explanation of Decision Result.
- Keep execution trace and diagnostics available to integrators, but collapsed or hidden by default for business users.
Use /api/v1/decide for both Prepared Criteria Mode and business-data integrations that submit a businessData object. New public onboarding should prefer Preview Decision and Execute Decision terminology.
The exact fields depend on the selected Tire Retail & Service decision. The example below shows the integration style rather than a guaranteed schema for every decision.
{
"decisionId": "AUTO-TIRE-028",
"decisionPreparationModelId": "AUTO-TIRE-PROFILE-STANDARD",
"scenarioId": "AUTO-TIRE-SCENARIO-MAINTENANCE-PACKAGE",
"businessData": {
"candidates": [
{
"optionId": "PKG-ALIGN-ROTATE-TPMS",
"name": "Alignment, rotation, balance, and TPMS inspection",
"values": {
"safetyBenefitScore": 88,
"customerNeedFitScore": 82,
"serviceCapacityScore": 76,
"grossMarginScore": 71,
"vehicleConditionScore": 84,
"customerAcceptanceScore": 69
}
},
{
"optionId": "PKG-ROTATE-BALANCE",
"name": "Rotation and balance package",
"values": {
"safetyBenefitScore": 71,
"customerNeedFitScore": 79,
"serviceCapacityScore": 91,
"grossMarginScore": 63,
"vehicleConditionScore": 76,
"customerAcceptanceScore": 86
}
}
]
},
"requestContext": {
"correlationId": "tire-service-20260717-001"
}
}
This pattern belongs in a trusted backend, not directly in browser JavaScript.
async function executeTireDecision(decisionInput, jwtToken) {
const response = await fetch(`${process.env.DECISIOQ_BASE_URL}/api/v1/decide`, {
method: "POST",
headers: {
"Authorization": `Bearer ${jwtToken}`,
"Content-Type": "application/json"
},
body: JSON.stringify(decisionInput)
});
if (!response.ok) {
throw new Error(`DecisioQ execution failed: ${response.status} ${await response.text()}`);
}
return await response.json();
}
| UI Element | Recommended Display | Why It Matters |
|---|---|---|
| Choose a Decision | Sector, Category, Decision, Profile, and Scenario selectors populated from catalog metadata. | Users see business names while integrators retain stable IDs. |
| Selection Overview | Sector, category, and decision overviews in one collapsible panel. | Service advisors, managers, and digital retail users understand the decision before entering data. |
| Guided Data Collection | Criterion label, field, data type indicator, summary, and expandable "More about this criterion". | Improves fitment, inventory, service, warranty, and fleet account data quality. |
| Candidate Cases | Two fields per row where practical, editable option ID, and visible units or data type indicators. | Users can compare tire options, service packages, suppliers, appointments, or warranty outcomes quickly. |
| Decision Result | Recommendation, ranking, confidence, and key drivers. | Users need the answer and the reason. |
| Outcome Follow-up | Accepted, Rejected, or Overridden; selected option and override reason when applicable. | Connects the recommendation to the action actually taken. |
| Realized Value | Outcome status plus a consistently defined financial or operational metric. | Measures adoption and business value without changing deterministic scoring. |
| Explanation | Business-friendly explanation without AI provider branding. | Supports trust while keeping the UI provider-neutral. |
| Diagnostics | Collapsed technical panel for status, timings, warnings, and errors. | Useful for integrators without distracting business users. |
- Store identity credentials, Decision API base URL, and proxy configuration in trusted server configuration or a secret manager.
- Do not expose bearer tokens or integration credentials in browser code, kiosks, mobile apps, or online checkout pages.
- Use catalog metadata rather than hard-coded categories, decisions, criteria, profiles, or scenarios.
- Validate Business Data before execution and show user-friendly validation messages.
- Persist correlation ID, VIN, tire SKU, quote ID, repair order ID, appointment ID, fleet account ID, decision ID, profile ID, scenario ID, selected option, score, and explanation for audit.
- Retain the successful decision response
requestIdwith the host business transaction, then callPOST /api/v1/decision-outcomeswhen the action and realized result are known. - Require an
overrideReasonfor overridden recommendations; never infer acceptance merely because a result was displayed. - Monitor
GET /api/v1/decision-outcomes/summaryfor acceptance rate, override rate, and realized-value aggregates. Treat outcome feedback as reporting evidence, not automatic model training. - Redact customer identifiers, fleet contract details, supplier cost data, payment data, and sensitive warranty evidence in logs and diagnostics.
- Monitor catalog load failures, token refresh failures, API latency, validation failures, account verification failures, and unusual exclusion rates.
- Define fallback behavior so POS, eCommerce, shop scheduling, warranty, and fleet workflows remain usable when DecisioQ is unavailable.
- Review Decision Preparation Models and scenario assumptions with merchandising, store operations, fleet, inventory, and service leaders when seasonal demand or supplier policy changes.
| Symptom | Likely Cause | Fix |
|---|---|---|
| Category list is empty. | The catalog response does not include categories for the selected sector, or the client is reading an old category layer. | Use selectedSector.categories[] from /decisioncatalog. |
| Decision dropdown shows IDs only. | The client did not load decision detail or category decision names. | Display Decision Name as the label and keep decision ID as the option value. |
| Criterion guidance is missing. | Decision detail lacks criterion overview metadata or the page is not rendering it. | Read criterion overview from /decisioncatalog/decisions/{decisionId} and show available summaries. |
| Secure session could not be refreshed. | Token proxy or identity service configuration failed. | Check server-side identity configuration and proxy logs; do not request tokens directly from browser JavaScript. |
| Decision execution failed. | Decision API unavailable, invalid Business Data, authorization failure, or account verification issue. | Check response envelope, HTTP status, correlation ID, Decision API health, and server logs. |
| Unexpected recommendation. | Scale, units, direction, or values do not match catalog criterion guidance. | Compare Business Data fields against criterion overview and validation metadata. |
| Tire recommendation or appointment result seems stale. | Fitment, stock, supplier, bay, or appointment data changed after the decision input was prepared. | Refresh operational data close to execution time and include data freshness where available. |
