Skip to main content

Template API

The HTTP contract an OEM ordering system uses to obtain order templates and report what it placed. The machine-readable contract is template-api.v2.yaml (OpenAPI 3.1) and is normative: this page covers only what a schema cannot say.

See Externally triggered runs for where the API sits in the platform.

What the API is for​

An OEM that runs its own order management places its own orders. We produce validated templates; they decide what to do with them. The API is the entire boundary — the calling system reads no warehouse table and holds no warehouse credentials — and it never submits an order.

Three endpoints​

POST /templatesAsk for templates for a month's volumes
GET /templates/{id}The request, and its templates once ready
POST /order-statusReport what was placed

The resource is named for what the caller asked for, not for how we produce it. A caller creates a template request, asks after it, and collects its templates. Nothing in the contract describes the work behind the API, so that work can change without the contract lying.

Why the contract is asynchronous​

A request covers every dealer and model in a month's volumes and takes minutes. Posting one therefore returns its identifier and a URL; it does not wait.

A caller's loop is:

  1. POST /templates → an id and a URL.
  2. GET /templates/{id} while status is accepted or running.

Poll on the in-flight statuses. A request ends on any status other than accepted and running, failed and cancelled included, so a caller waiting for succeeded polls forever when every model fails.

There is no separate results call. The same GET answers both questions: while the request runs it returns status, per-model counts and any errors so far, and once it finishes it also returns the templates. Polls before completion stay small, and the caller stops at the one that reports a terminal status.

A request whose models did not all succeed reports partially_succeeded. It holds the templates that were produced, and errors names each model that produced none, so a caller orders what it has rather than discarding the request.

Collecting templates​

Templates arrive one of two ways, and a caller must handle both: templates inline, or templatesUrl pointing at newline-delimited JSON under a link that expires. Which one depends on size, and the same monthly request can answer differently as volumes change. Passing modelCode narrows a large request to one model at a time.

Template classification​

Every template has a templateType, either control_template or predictive_template. It is required, and it changes the order the OEM system places.

Unlike templateId, the value is not stored and quoted back. Copy it onto the order exactly as received, including case. Dropping it, or changing its case, places a different order from the one we validated.

The API classifies only what it selected. Whether an order draws on a pool of vehicles assigned to dealers at a later stage belongs to the OEM's allocation process, and no field here reports it.

Repeating a request​

POST /templates takes an Idempotency-Key. A repeat with the same key returns the request that key already created; a repeat with the same key and a different body is refused. Network retries are therefore safe, and a caller that loses an id recovers it by replaying the request with its original key.

Reporting what was ordered​

POST /order-status ties each order the OEM system created back to the templateId that recommended it.

The call is not scoped to one template request. A templateId identifies both the template and the request it came from, so one report may span several requests and the caller never has to group outcomes by request. Send a single outcome as each order is placed, or batch them.

Only templates that were acted on are reported. A template nobody ordered is left out, rather than reported with a status meaning "not ordered" — there is no event for a decision not to act, so there is no status for one either.

status is SUCCESS, FAILURE or CANCELLED. Placement and modification are not separate statuses: the template's action already says which it was.

Reports are cumulative. A later report for a templateId replaces the earlier one, so a template placed and then cancelled is reported twice and ends as CANCELLED.

This is how placement outcomes reach the warehouse. Reporting reads a request's recommendations and its placements together, in one format, regardless of who placed them.

Production timing binds the template​

A request names the production weeks it may assign. An option can be orderable for one week and not the next, so a template is only valid for the week it was built against.

Each week takes an optional count, used when distributing templates across the weeks.

Each template names its week in productionWeek. Order the template in the week it names. Assigning a different week after collecting templates orders a configuration nobody validated.

Steering scope​

A take-rate target attaches to a scope rather than to the request as a whole. A scope is a region, or the entire population when the scope is empty.

The scope decides the population the target's share is measured over. A target of 0.8 over a region means eighty percent of that region's orders for the model. It does not mean eighty percent at each dealer in the region.

A target names one option code. Rates and tolerances are fractions between 0 and 1 throughout.

Authentication​

A gateway-issued key in the apikey header identifies the calling system and selects its rate limit.

The key determines the tenant. A tenant is the brand and the market it sells in taken together: BMW-US and BMW-AG are two tenants, not one brand in two markets. Nothing in the request body names either, and a request that does is rejected — the key is what the gateway authenticated, and a body is a claim the caller makes about itself.

The gateway holds one consumer per calling system, and each consumer's key is bound to one tenant. Resolving the key to that tenant is the gateway's job; the API receives it already resolved and never infers it from the payload.

One tenant is served: BMW-US. A key bound to any other authenticates and then receives 403. Adding a tenant is provisioning a consumer, not a contract change.