CH18-02: Integration Requirements, Contracts, and Ownership
Goal
This section defines integration requirements through contracts, data ownership, versioning, failure behavior, security, and operating responsibility.
The previous section framed integration as controlled boundary crossing. This section turns that mental model into requirements. Before you choose API Management, Service Bus, Event Grid, Logic Apps, Event Hubs, or a data pipeline, you need to know what agreement the systems are making with each other.
The durable idea is:
An integration contract should explain meaning, ownership, and failure behavior, not only fields and endpoints.
The Short Version
An enterprise integration contract is an operating agreement. It says what data or action is being exchanged, who owns its meaning, how it is secured, what versions are valid, what happens when it fails, how it is monitored, and who responds when something breaks.
A schema tells you that a field named deliveryStatus exists. A contract tells you whether delivered means the carrier scanned the package, the customer received it, the marketplace was notified, finance can recognize revenue, and support can close a case. That difference matters in commerce because integration data often becomes a customer promise, a seller promise, an inventory decision, or a financial record.
The Contract Checklist
Use this chain when defining an integration:
Contract -> owner -> schema/version -> auth -> retry/replay -> monitoring -> support pathEach part answers a different architecture question.
| Contract Area | What It Defines | Example Question |
|---|---|---|
| Business meaning | What the API, event, message, file, or sync represents. | Does OrderAccepted mean paid, fraud-checked, inventory-reserved, or only received? |
| Owner | Which team owns the meaning, changes, and support. | Does commerce, warehouse, finance, or central integration own this contract? |
| Shape and version | Payload fields, schema version, compatibility rules, and deprecation windows. | Can a new optional field be added without breaking consumers? |
| Security | Identity, authorization, data classification, secrets, certificates, and network path. | Is this partner allowed to see customer address data? |
| Failure semantics | Timeout, retry, dead-letter, compensation, replay, and manual review behavior. | If tax calculation fails, does checkout stop, retry, estimate, or route for review? |
| Observability | Correlation IDs, logs, metrics, status, dashboards, alerts, and audit records. | Can support trace an order across storefront, tax, fraud, payment, warehouse, and carrier? |
| Support path | Runbook, escalation owner, service level, and incident process. | Who acts when a partner feed starts rejecting valid messages? |
This checklist keeps the conversation practical. It also prevents a common trap: treating integration as a technical payload discussion while the actual risk is business ambiguity.
Types of Contracts
Different integration styles create different contract shapes.
| Integration Type | Contract Should Include | Common Commerce Use |
|---|---|---|
| API contract | Operations, request and response schemas, authentication, authorization, status codes, rate limits, timeout behavior, and versioning. | Seller management, tax quote, fraud decision, customer support lookup. |
| Message contract | Command meaning, required metadata, ordering needs, idempotency key, retry behavior, dead-letter policy, and owner. | Release order to warehouse, request refund processing, submit invoice generation. |
| Event schema | Event meaning, producer, consumers, version, timestamp, correlation ID, replay rules, and compatibility rules. | Order shipped, inventory adjusted, return received, seller approved. |
| File contract | Format, schedule, location, encryption, validation rules, acknowledgements, retention, and correction process. | Supplier product feed, carrier reconciliation, finance batch export. |
| Data synchronization contract | Source of truth, sync frequency, conflict behavior, freshness expectation, lineage, and reconciliation. | CRM order visibility, finance reporting, support timeline, analytics store. |
Notice that every contract has technical and operating parts. The schema is necessary, but it is not enough.
Ownership of Meaning
Central integration teams often provide gateways, messaging infrastructure, workflow tooling, standards, and reusable patterns. That does not mean they own every business definition.
In a commerce platform, the domain team closest to the business outcome should own the meaning of the contract. The order domain owns order lifecycle events. The fulfillment domain owns warehouse release and shipment readiness messages. Finance owns settlement and reconciliation meanings. Customer service owns support-facing case and contact integrations.
The central integration team can own platform rules such as naming standards, policy enforcement, shared observability, API publication, partner onboarding processes, and common reliability patterns. This split avoids two unhealthy extremes:
Every team building point-to-point integrations with no shared guardrails.
A central integration group becoming responsible for business meaning it cannot safely interpret.
Failure Semantics Are Part of the Contract
Every integration should say what kind of failure it can tolerate.
| Failure Behavior | Meaning | Example |
|---|---|---|
| Retryable | The same operation can be attempted again safely. | A carrier API returns a temporary 503 response. |
| Terminal | Retrying will not help without changing the input or process. | A supplier file is rejected because required fields are missing. |
| Compensating | A later action is needed to correct or reverse an earlier action. | A refund request succeeds after an invoice has already been exported. |
| Replayable | A message or event can be processed again from a known point. | Warehouse missed a shipment event and requests replay for a time window. |
| Manually reviewed | Human decision or correction is required. | A tax provider response is inconsistent for a regulated address. |
If the contract does not define failure behavior, teams invent behavior during incidents. That usually means inconsistent retries, duplicate work, unclear ownership, and incomplete audit evidence.
Example: Tax Provider Contract
Tax calculation is a useful example because checkout depends on it, but the commerce platform may not own the external tax engine.
The contract should define the input data, such as billing address, shipping address, product categories, seller location, buyer type, discounts, shipping charges, and tax exemption status. It should define the response meaning, such as estimated tax, final tax, jurisdiction breakdown, provider reference, and validity window. It should define timeout behavior: how long checkout waits, whether a retry is allowed, and what the customer sees if the provider is unavailable.
It should also define audit needs. Finance and compliance may need to know which tax provider version produced the calculation, what inputs were sent, what response came back, and whether later correction is possible.
That is far more than an endpoint and a JSON document. It is an operating agreement around a customer-visible and finance-sensitive decision.
Common Mistakes
Treating schemas as technical details without business ownership. The field names may be technical, but their meaning affects customers, sellers, finance, support, and operations.
Versioning only after consumers break. Versioning, compatibility, and deprecation windows should be part of the contract from the beginning.
Failing to define retry and replay behavior. A message is not safely replayable just because it can be read again. The receiving system must handle duplicates and preserve business correctness.
Letting central integration own every business interpretation. Platform teams can own integration capability; domain teams must still own domain meaning.
If Someone Asks You
What should an enterprise integration contract include?
It should include the business meaning, owner, schema or payload version, security requirements, authorization rules, data classification, failure behavior, retry and replay rules, observability, audit evidence, support path, and change process. In enterprise commerce, a contract is not just the shape of a request or event. It is the agreement that lets teams operate safely across boundaries.
What You Should Remember
Contracts are operating agreements, not just payload shapes.
Questions to Check Your Understanding
Who should own the business meaning of an event such as
OrderShippedorRefundApproved?What must be true before an integration is safely replayable?
Why should timeout, retry, and manual review behavior be part of an integration contract?