Order types

An order type answers “what is this call for?”. You reference one by key on every order, and it decides which vetted agent behaviour runs, what context you must supply, and what the negotiation corridor defaults to.

Keys are German

The taxonomy is German because the domain is:

Key	Purpose
forderungsuebernahme	First contact after a case is handed over: establish reachability and identity, name the claim.
zahlungserinnerung	A friendly reminder after the due date, before formal dunning.
mahnung	Formal dunning notice.
zahlungsversprechen_nachfassen	A promised payment has not arrived.
ratenplan_nachfassen	An instalment was missed.
titulierung_ankuendigung	Announcing escalation to a titled claim.

These are identifiers, not display strings. Read title and description from GET /v1/order-types for anything you show a user, and treat the key as opaque.

Caution

Passing an English key such as payment_reminder returns 422 unknown_order_type unless that alias has been seeded for your tenant explicitly. Always list the order types available to you rather than assuming a key exists.

Why you cannot choose a conversation profile

conversation_profile binds an order type to agent behaviour that Pace has reviewed. You cannot reference a profile Pace has not created for your tenant, and you cannot describe the behaviour you want in free text on an order.

That binding is what makes “no marketing calls over this API” an enforceable property rather than a sentence in a contract. If the behaviour were a parameter, the promise would rest on nobody setting it wrongly.

There is a second, more concrete reason. A profile carries the spoken text of the conversation, including how the agent introduces itself. Referencing a profile configured for a different tenant would have the agent say that other tenant’s name out loud to your debtor. The restriction is what prevents it.

New profiles are created during onboarding with Pace. Once they exist, mapping them to order types is yours to manage.

Versions are pinned at acceptance

Every order records order_type_version at the moment it is accepted, and that value never changes.

Without it, a result would stop being interpretable the first time you edited the order type: you would have no way to know which negotiation corridor was in force when that particular call ran. With it, a result from March stays readable in September.

A PATCH that changes behaviour bumps the version. Orders already in flight keep the version they were accepted under.

Required context

required_context lists what an order must carry. claim is always required. Some types also require history - zahlungsversprechen_nachfassen is meaningless without the promise it is following up on, so the API refuses an order that omits it rather than letting the agent improvise.

Missing context comes back as 422 missing_required_context, with the field in errors[].pointer.

variables_schema

An order type may define a JSON Schema for context.variables. Anything you send there is validated against it at acceptance.

{
  "variables_schema": {
    "type": "object",
    "properties": {
      "contract_number": { "type": "string" },
      "product_line":    { "type": "string", "enum": ["basic", "premium"] }
    },
    "required": ["contract_number"]
  }
}

This is worth defining. A typo in a variable name is otherwise invisible until the agent tries to speak a value it does not have.

Managing order types yourself

Three writes, all requiring config:write:

1. Create - POST /v1/order-types

   A new order type starts as a draft. Drafts cannot be used on orders.

2. Update - PATCH /v1/order-types/{key}

   Change the listed fields. Setting status: "active" publishes a draft. Behavioural changes bump the version.

3. Archive - POST /v1/order-types/{key}/archive

   No new orders may reference it. Orders already accepted keep running and keep their pinned version.

Two things you cannot do, both deliberately:

You cannot rename a key. The key is the identifier, and completed orders carry it. Renaming it would alter the provenance of work that is already finished.

You cannot archive through PATCH. Archiving has its own conflict case - an order type still referenced by running orders behaves differently from an unused one

• and folding that into a field change would hide it. It gets its own sub-action.

Defaults and narrowing

defaults on an order type supplies scheduling, negotiation and locale for orders that do not specify them. An order may override them, but only to narrow:

effective corridor = order type corridor ∩ what the order sends

An order asking for twelve instalments against a type that permits six gets six - or, where the mismatch is not resolvable by narrowing, 422 negotiation_exceeds_policy. The corridor on the order type is a ceiling, not a suggestion.

Note

The request form of defaults is fail-closed: unknown fields are rejected. A typo there would otherwise create an order type quietly running the default negotiation corridor, and you would never find out. The response form is fail-open, so your client does not break when the object is extended.