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.
1Tire Retail & Service Overview

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.

2Catalog Discovery Flow

Tire Retail & Service client applications should use the same discovery flow as the Business Decision Studio:

  1. Load GET /decisioncatalog through the approved server-side Decision Catalog gateway.
  2. Populate Sector from catalog.sectors[] and select AUTO-TIRE for Tire Retail & Service.
  3. 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.
  4. Populate Decision from selectedCategory.decisions[] when available, or call /decisioncatalog/sectors/{sectorCode}/categories/{categoryCode}/decisions.
  5. Display Decision Name only in the dropdown while keeping decisionId as the option value.
  6. 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.

3Tire Retail & Service Use Cases
Use CasePrimary UsersTypical Inputs
Tire recommendation and fitmentService advisors, digital retail, call center, fleet account teamsVehicle fitment, tire size, driving conditions, season, budget, inventory, warranty, brand preference.
Appointment and service bay prioritizationStore managers, service advisors, scheduling systemsCustomer urgency, tire availability, bay capacity, technician skill, service duration, fleet priority.
Warranty and goodwill handlingCustomer service, warranty administrators, store managersPurchase age, tread depth, damage type, road hazard coverage, evidence quality, customer value.
Supplier and fulfillment selectionCounter staff, purchasing, eCommerce operationsLocal stock, warehouse stock, supplier availability, landed cost, lead time, rebate, service promise.
Inventory replenishment and forecastingInventory planners, store managers, warehouse teamsSales velocity, seasonality, on-hand quantity, stockout risk, margin, forecast, transfer cost.
Commercial fleet tire serviceFleet account managers, service operationsFleet SLA, vehicle downtime risk, tire condition, route duty cycle, replacement urgency, contract terms.
Maintenance package recommendationService advisors, digital retail, customer retention teamsAlignment need, rotation status, TPMS state, inspection results, customer preference, service history.
Digital retail and business strategyOperations leaders, product teams, store leadershipBusiness value, customer impact, implementation effort, data readiness, ROI, adoption risk.
4Business Data Mapping

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 SourceCommon UseIntegration Notes
VIN, vehicle ID, tire SKU, quote ID, repair order ID, appointment ID, fleet unit ID, or warranty claim IDoptionId 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 dataTire recommendation, compatibility, substitute tire, digital retail guidance.Separate confirmed fitment, size compatibility, speed/load rating, season type, and product attributes.
Inventory and supplier dataFulfillment, 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 dataBay 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 dataReplacement, 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 dataRecommendation, 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 dataPricing, 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.

5Preview and Execute Workflow

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.

  1. Trusted backend obtains a JWT token from identity.vinquery.com.
  2. Application loads catalog and decision detail metadata.
  3. User or system prepares Business Data for candidate tires, service slots, suppliers, warranty outcomes, inventory actions, fleet service options, or strategy investments.
  4. Call POST /api/v1/validate to validate and prepare the decision input before execution.
  5. Call POST /api/v1/decide to return the authoritative Decision Result.
  6. Display the recommendation, ranked alternatives, warnings, assumptions, and Explanation of Decision Result.
  7. 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.

6Example Request Shape

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"
  }
}
7Backend Call Pattern

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();
}
8UI and Workflow Integration
UI ElementRecommended DisplayWhy It Matters
Choose a DecisionSector, Category, Decision, Profile, and Scenario selectors populated from catalog metadata.Users see business names while integrators retain stable IDs.
Selection OverviewSector, category, and decision overviews in one collapsible panel.Service advisors, managers, and digital retail users understand the decision before entering data.
Guided Data CollectionCriterion label, field, data type indicator, summary, and expandable "More about this criterion".Improves fitment, inventory, service, warranty, and fleet account data quality.
Candidate CasesTwo 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 ResultRecommendation, ranking, confidence, and key drivers.Users need the answer and the reason.
Outcome Follow-upAccepted, Rejected, or Overridden; selected option and override reason when applicable.Connects the recommendation to the action actually taken.
Realized ValueOutcome status plus a consistently defined financial or operational metric.Measures adoption and business value without changing deterministic scoring.
ExplanationBusiness-friendly explanation without AI provider branding.Supports trust while keeping the UI provider-neutral.
DiagnosticsCollapsed technical panel for status, timings, warnings, and errors.Useful for integrators without distracting business users.
9Production Readiness
  • 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 requestId with the host business transaction, then call POST /api/v1/decision-outcomes when the action and realized result are known.
  • Require an overrideReason for overridden recommendations; never infer acceptance merely because a result was displayed.
  • Monitor GET /api/v1/decision-outcomes/summary for 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.
10Troubleshooting
SymptomLikely CauseFix
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.