Designing a Source-to-Talon.One Data Contract

Welcome. This module turns Talon.One entities into an integration design that a commerce, CRM, and promotion team can implement without relying on implicit assumptions.

The goal of this lesson is to produce a source-to-Talon.One data contract for a concrete commerce journey. Rather than treating an API payload as a loose collection of fields, you will define where each field originates, what it means, which Talon.One entity owns it, when it is sent, and who remains authoritative for it.

---

A data contract is more than a JSON schema

A JSON schema answers: Can this payload be parsed? An integration data contract answers the more important architectural questions:

• What business fact does this field represent?
• Which enterprise system is authoritative for that fact?
• Which Talon.One entity should contain it?
• How long is it valid?
• At which customer or transaction event is it updated?
• What type, unit, and allowed values does it have?
• What happens when the field is absent, changed, or no longer true?

For Talon.One, the central distinction is between durable customer facts and transaction-specific facts:

• A customer profile represents a customer over many journeys.
• A customer session represents one promotion-evaluated journey, commonly a cart and checkout lifecycle.
• A cart item represents a line in that session’s cart.
• An event represents a discrete occurrence, such as an app install or a product review, rather than a changing transaction state.
• A campaign and its rules represent promotion logic configured in Talon.One, not facts supplied by the shopper or commerce platform.

This is a useful boundary: the commerce platform reports facts; Talon.One evaluates configured promotion logic against those facts and returns decisions as effects.

A custom attribute therefore needs an explicit definition before runtime data can safely use it. For each custom field, record:

Contract element	Example
Business meaning	City of the selected delivery address for this checkout
Talon.One entity	Customer session
API name	shippingCity
Type	String
Authoritative source	Checkout delivery-address service
Update moment	When the shopper selects or changes delivery
Rule purpose	Limit a regional free-shipping promotion
Validity	Only for this customer session

The critical design decision here is the entity. A shipping city selected during checkout belongs on the customer session, even if the customer profile also has a saved default address. The saved address is a durable customer preference; the selected address is a fact about the current order attempt. Confusing the two can lead to rules using stale profile data instead of the actual delivery choice.

---

Sample journey: signed-in checkout with a coupon

Consider a retailer with this journey:

1. A shopper adds a shampoo and conditioner to a web cart.
2. They sign in during checkout.
3. They choose delivery to Seattle.
4. They enter the WELCOME10 coupon.
5. The checkout service asks Talon.One to evaluate promotions.
6. Payment and order confirmation succeed.
7. The commerce system closes the Talon.One session.

Assume the business has two promotions:

• WELCOME10: a coupon-based discount for eligible first-time customers.
• Free standard delivery for qualifying carts delivered to Seattle.

The contract must carry only facts required to evaluate those rules. It should not send the rule outcome as an input. For example, do not send fields such as isEligibleForWelcomeOffer or couponAccepted: those are decisions Talon.One should derive from campaign rules and return as effects.

---

The contract’s ownership model

Before writing a payload, establish the systems of record. Talon.One is not a replacement for a customer master, product information system, order-management system, or payment service. It is the system that evaluates promotion and loyalty rules and maintains the promotion state it is configured to manage.

For the sample journey, use this ownership model:

Information domain	System of record	Talon.One role	Contract implication
Customer identity	Identity service or CRM	Profile representation for promotion evaluation	Use the enterprise customer key as the profile integration ID.
Customer segment	CRM or customer-data platform	Readable profile attribute used by rules	Synchronize the current eligible segment when it changes.
Product SKU, name, and merchandising category	Product catalog or commerce catalog	Cart-item facts used in rules	Send the actual items being purchased, using stable product identifiers.
Cart quantities and base selling prices	Cart and pricing service	Session cart used for evaluation	Send an authoritative current cart snapshot during checkout.
Delivery method and destination	Checkout service	Session attributes for this checkout	Send only after the shopper selects these values.
Coupon code entered	Checkout UI and checkout service	Candidate code supplied for evaluation	Send the code, but let Talon.One determine acceptance or rejection.
Campaign rules, coupon constraints, and budgets	Talon.One, under promotion-team governance	Promotion decisioning configuration	Do not reconstruct this logic in checkout code.
Payment authorization and order confirmation	Payment service and order-management system	External finalization signal	Close the session only when the chosen business completion point has occurred.
Shipment, fulfillment, and refund execution	Order-management and fulfillment systems	Consumer of returned effects where applicable	Never treat a Talon.One effect as proof that an external fulfillment action happened.

Two boundaries deserve emphasis.

First, Talon.One should receive a representation of the cart, not become the cart system of record. Checkout remains responsible for availability, tax, shipping calculation, payment, and durable order records.

Second, the commerce system must consume Talon.One effects, but it remains responsible for applying them correctly to its own pricing and order systems. The returned response is a decision interface, not a new order ledger.

---

Define entity placement and attribute semantics

For this journey, define three custom attributes. These are deliberately few: every attribute expands the integration surface, test matrix, privacy footprint, and rule-authoring vocabulary.

API name	Talon.One entity	Type	Meaning	Source and lifecycle
customerSegment	Customer profile	String	Current marketing or customer-service segment, such as consumer or partner	CRM is authoritative; update when segment membership changes.
shippingCity	Customer session	String	City on the delivery address selected for this checkout	Checkout service is authoritative; update when address selection changes.
brand	Cart item	String	Merchandise brand as classified by the commerce catalog	Catalog service is authoritative; include on every relevant cart-item snapshot.

A few placement rules make the mapping defensible:

1. Put a value on the profile only when it describes the customer across multiple transactions. A CRM-maintained segment is a suitable example.
2. Put a value on the session when it describes the current cart, checkout, or order attempt. Delivery city, selected fulfillment method, acquisition channel, and gift-wrap choice commonly belong here.
3. Put a value on the cart item when it differentiates merchandise lines. Brand, collection, supplier, margin band, or restricted-product status are examples.
4. Use an event when the fact is a discrete occurrence rather than a current state. “Customer completed a product review” is an event; “customer has three reviews” may be a profile attribute if it is maintained as a durable aggregate.
5. Do not duplicate a fact on several entities merely to make rules easier to write. Duplication creates synchronization and precedence problems.

Also specify price semantics. In this sample contract, price means:

The current per-unit merchandise price in the Application’s configured currency, after ordinary catalog or contract pricing but before discounts calculated by Talon.One; tax and delivery charges are excluded unless the pricing policy explicitly says otherwise.

That convention must be documented and applied consistently. If one channel sends tax-inclusive prices and another sends tax-exclusive prices, a percentage discount can be mathematically correct yet commercially wrong.

---

The runtime payload contract

The following is a representative payload sent by a trusted server-side checkout integration. It is not intended to be constructed directly by a browser or mobile client.

{
  "customerSession": {
    "profileId": "cust-004218",
    "state": "open",
    "cartItems": [
      {
        "name": "Aster Repair Shampoo",
        "sku": "AST-SHAM-250",
        "quantity": 1,
        "price": 14.50,
        "category": "Haircare",
        "attributes": {
          "brand": "Aster"
        }
      },
      {
        "name": "Aster Repair Conditioner",
        "sku": "AST-COND-250",
        "quantity": 1,
        "price": 15.50,
        "category": "Haircare",
        "attributes": {
          "brand": "Aster"
        }
      }
    ],
    "couponCodes": [
      "WELCOME10"
    ],
    "attributes": {
      "shippingCity": "Seattle"
    }
  }
}

The checkout service submits this representation with the documented Update customer session endpoint:

PUT /v2/customer_sessions/web-cart-78231

The session identifier, web-cart-78231, is generated and owned by the commerce platform. It should be stable for the entire promotion-evaluated cart lifecycle. A useful convention is to include a channel prefix where cart identifiers are not globally unique, such as web-cart-78231 or store-transaction-48219.

The data contract should state that:

• profileId is the stable enterprise customer identifier, not an email address and not a temporary login token.
• sku is a stable sellable-item identifier, not a display name.
• quantity is the currently requested number of units for that cart line.
• price follows the agreed price convention and is supplied by the authoritative pricing service.
• couponCodes contains codes submitted by the customer; it does not indicate whether those codes have been accepted.
• Session attributes describe the current checkout state.
• Cart item attributes are supplied as a complete authoritative set for each item. Talon.One’s attribute documentation specifically notes that cart-item attributes omitted from the supplied list are removed, so partial attribute construction can accidentally erase data needed by rules.

During cart changes, the integration should send the current, internally validated cart representation rather than attempt to infer deltas from the previous Talon.One response. A shopper can add an item, change quantity, remove an item, change a coupon, or choose another address. Each such change may alter eligibility and returned effects.

When the order reaches the agreed business completion point, the commerce backend updates the same session to closed. The Integration tutorial notes that closing can finalize promotion consequences such as coupon redemption and budget counters. Therefore, closing a session is not merely cleanup; it must be aligned with the organization’s order-confirmation policy.

---

A compact contract specification

A strong implementation artifact makes the preceding decisions explicit. For the sample journey, a concise version could read as follows.

Contract: checkout promotion evaluation

Purpose
Evaluate coupon and delivery promotions for a web checkout, then finalize applicable promotion state when the order is confirmed.

Participants

Participant	Responsibility
CRM / identity service	Provides stable customer ID and durable customer segment.
Product catalog and pricing service	Provides product identity, classification, and current base unit price.
Checkout service	Constructs the authoritative cart snapshot and invokes Talon.One.
Talon.One	Evaluates active campaign rules and returns effects.
Order-management system	Confirms the order and triggers session closure.

Inbound data to Talon.One

Field	Source	Talon.One destination	Rule-safe definition
Enterprise customer ID	Identity service	CustomerProfile.integrationId, referenced as profileId in a session	Immutable, non-PII business key where possible.
Customer segment	CRM	Customer profile attribute customerSegment	Controlled String value; CRM remains authoritative.
Cart ID	Checkout service	Customer session integration ID in endpoint path	Stable for one cart or order attempt; unique within the Application.
SKU	Catalog service	cartItems[].sku	Stable sellable SKU, not a human-readable title.
Product name	Catalog service	cartItems[].name	Current display name; not used as a durable product key.
Product category	Catalog service	cartItems[].category	Controlled merchandising taxonomy value.
Brand	Catalog service	cartItems[].attributes.brand	Controlled String; custom cart-item attribute.
Quantity	Cart service	cartItems[].quantity	Current requested unit quantity.
Base unit price	Pricing service	cartItems[].price	Per-unit price under the documented pricing convention.
Coupon input	Checkout service	couponCodes	Customer-submitted candidate coupon code.
Selected delivery city	Checkout service	Session attribute shippingCity	Current delivery address city; custom session attribute.
Transaction status	Order-management system	state	open during evaluation; closed only at the agreed finalization point.

Outbound data from Talon.One

The checkout adapter receives Talon.One effects and exposes them to the commerce domain as typed promotion decisions, for example:

• a discount to apply,
• an accepted or rejected coupon state,
• a notification to display,
• a fulfillment-related instruction that requires a downstream system.

The adapter must not rely on the order of effects in a response. It should interpret each effect by its type and properties, then let the relevant commerce component apply the decision. Later lessons will examine effect handling and reconciliation in detail.

---

Change control and contract tests

A data contract needs operational governance. Adding shippingCity to a rule is not merely a rule-builder change: it creates a dependency on a custom attribute, the checkout source, the request builder, and test coverage.

Use these rules for changes:

• Add a field intentionally. Specify entity, type, source, allowed values, privacy classification, and rollout order before a rule depends on it.
• Do not rename API names casually. Rules and integrations can both depend on them.
• Version the semantic definition. A field whose meaning changes from “list price” to “discounted selling price” is a breaking change even if its JSON type remains a number.
• Test missing and stale values. Verify what happens if a shopper has no profile, has no delivery selection yet, enters an invalid coupon, or changes cart quantity.
• Use realistic Application boundaries. If regions operate in different currencies or have isolated catalogs and promotion ownership, the Application design must prevent incompatible data from being evaluated together.
• Minimize personal data. Do not send email addresses, payment data, full addresses, or device identifiers merely because Talon.One can store attributes. Send only what a promotion or loyalty rule genuinely needs.

A practical sandbox checkpoint is to create the three custom attributes in the contract, submit an open session with the sample cart, and inspect the stored session and returned response. Then change the delivery city or remove the coupon and confirm that the next request reflects the full current checkout state rather than an outdated mixture of facts.

---

Key takeaways

A Talon.One data contract is an executable agreement between source systems, the checkout integration, and promotion operations.

• Model durable customer facts on customer profiles and one-journey facts on customer sessions.
• Represent purchasable lines as cart items, using stable SKUs and explicit price semantics.
• Define every custom attribute by business meaning, entity, type, API name, owner, and update moment.
• Keep CRM, commerce, catalog, payment, and fulfillment systems authoritative for their own domains; Talon.One owns promotion evaluation and configured promotion state.
• Send current, authoritative transaction data to Talon.One, then consume returned effects through a controlled integration boundary.
• Treat session closure as a business finalization event, not a technical afterthought.

Next, the course moves from the data supplied to Talon.One to the decision logic built from it: expressing a promotion as an event, conditions, and effects.