Does the part fit the vehicle? Checking the cart against the VIN

A customer puts three parts in the cart and types in their vehicle identification number. Two fit, one belongs to a different engine of the same series. If that does not surface at the checkout, it surfaces at installation — and then it costs shipping, return, credit note and an annoyed customer.

The cart check accepts the whole cart in one call. If the result is available at once, it comes back directly with 200. If a vehicle check cannot be completed immediately, the API answers with 202 and a jobId, and the result is collected via the status endpoint.

What this case requires

• A vehicle identification number from the customer. Without it there is no reference to check against.
• The cart lines as numbers. Free text in the cart is not a checkable object; that is why normalisation comes first.
• A place in the checkout that can wait for the result. If the API answers with 202, the result is only available via the status endpoint — the interface has to reflect that.
• A rule for what happens on `fits=false` with `complete=false`. Allow the order with a notice or block it: that is a commercial decision.
• The entitlement to query the vehicle. With the call you confirm that you are the keeper, the owner or demonstrably authorised or otherwise legally entitled, and that you use the identification number solely for the stated permissible purpose.

The sequence

The table names the responsible call per stage and what exists afterwards. The reasoning for why a stage cannot be skipped follows below it.

Why each stage is needed

1. Normalise the numbers. GET /parts/oe/normalize turns a retyped spelling into a lookupKey. Without this step you check hyphens and spaces too, and the cart fails on formatting.
2. Check the cart. POST /vin/cart-check takes one to 30 lines at once as oeNumbers, together with vin and the mandatory mode of type or vehicle. One call for the whole cart replaces a query per line; the response keeps the order and duplicates of the input.
3. Collect the result. After a 202 response, GET /vin/cart-check/jobs/{jobId} returns the status; on succeeded, result contains oe and fits per line and complete for the cart. If complete=false, a negative single result is not a definitive exclusion.

curl -X POST \
  -H 'X-Api-Key: <API_KEY>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: korb-88213' \
  -d '{"vin":"<VIN>","country":"de","mode":"vehicle","oeNumbers":["8K0959455K","1K0121207AK"]}' \
  'https://api.tapinomahub.com/vin/cart-check'

What you end up with

What remains is a checkout that warns the customer before they pay. That lowers the return rate, and it lowers it at the right end: not through stricter return terms but through fewer wrong orders.

Where to find this in the documentation

The binding field lists, error codes and sample responses live in this surface’s OpenAPI contract at docs.tapinomahub.com (tapinoma-hub). All use cases arranged by surface and role: overview of the use cases.