Order Management

Koddi brings order management together with media planning, IO associations, campaign execution, delivery, and reconciliation. Our native OMS is designed to connect commercial opportunities and agreements to the media that fulfills them, giving Sales, Account Management, Ad Ops, and Finance a shared view of the commercial-to-media lifecycle.

Using the native Koddi OMS can reduce duplicate setup, manual handoffs, and the ongoing work of synchronizing commercial and execution records across separate platforms. We recommend this approach wherever it meets your operational requirements.

Before proceeding with a third-party integration, keep the following in mind:

• A separate OMS is optional. You do not need to purchase or retain a third-party OMS simply to connect commercial orders to media execution in Koddi. Evaluate the built-in workflow first.

• You can retain your CRM and finance systems. Adopting Koddi’s OMS does not require replacing our CRM (like Salesforce) or your ERP. Define the appropriate handoffs so your CRM manages the sales relationship, Koddi manages the media workflow, and your finance system manages its agreed accounting and invoicing responsibilities.

• Use this guide when an external OMS must remain. The integration pattern below is intended for organizations with an existing OMS investment, enterprise architecture requirement, or specific workflow that calls for a separate system.

• External integrations introduce additional responsibilities. Object mapping, field ownership, synchronization, exception handling, reconciliation, and ongoing maintenance must be scoped and assigned. Compare that work with the native Koddi approach before committing to an integration.

• Validate feature scope and availability. Native OMS capabilities are delivered in phases. Confirm the features, configuration, commercial terms, and rollout timing applicable to your program. Signature integrations, revision workflows, advanced approvals, and role-specific work queues should be validated individually.

• This guide describes an integration design. References to third-party vendors do not establish a prebuilt connector, certified integration, included implementation service, or guaranteed feature parity. Agree on the supported operations and delivery scope with your Koddi team.

Recommended next step: Review your commercial-to-media workflow with Koddi and assess the built-in OMS first. If a third-party OMS remains part of the agreed architecture, use the integration guidance below.

Third-Party OMS Integration Scope

This guide describes an optional integration pattern for organizations retaining a third-party advertising Order Management System (OMS) alongside Koddi Ads. It uses APIs and persistent external identifiers to connect approved orders to media execution and return delivery data for reconciliation.

The OMS manages the commercial order, including products sold, approved terms, amendments, and billing instructions. Koddi translates the order into executable media and supplies delivery and performance results. An integration service connects the systems and manages synchronization.

This pattern can be adapted to an external third-party OMS or a custom system. The vendor’s APIs, your Koddi configuration, and the agreed workflow determine the implementation. Connector availability and scope should be confirmed with your Koddi team.

Integration Architecture

Use an integration service, either in your existing middleware or another agreed environment, to handle three workflows:

1. OMS to Koddi: Resolve advertisers, translate approved order lines into media, and apply approved changes.

2. Koddi to OMS: Return Koddi record IDs, execution status, delivery, and spend.

3. Reconciliation: Compare approved commitments with delivered media and prepare the information required by the OMS or finance system.

Use OMS events where available, or poll for changed records. Retrieve Koddi status and reporting through the appropriate APIs or an agreed data pipeline. Agree on event availability and refresh schedules during implementation.

If a CRM also feeds the OMS, designate one system as the source of media booking instructions. For example, CRM → OMS → Koddi avoids having both the CRM and OMS independently create campaigns for the same deal.

Object Relationships and Mapping

Koddi organizes execution through Advertisers, Media Plans, Campaigns, and Ad Groups. An IO represents the commercial authorization and can be associated with multiple campaigns. See Campaign Structure and the Salesforce integration guide.

Use the following as a starting mapping:

An OMS order can supply the commercial reference for both a Media Plan and an IO. They serve different purposes: the Media Plan describes the execution strategy; the IO governs the commercial commitment.

A commercial line may require several campaigns for different experiences or flights. Preserve its OMS line ID across those campaigns and assign a distinct execution key to each. If multiple OMS lines share a campaign, define how delivery will be attributed to each line before using that arrangement.

Map Ad Groups only when the OMS needs that level of control or reconciliation. Otherwise, aggregate their delivery through the mapped campaign.

Persistent Identifiers and Metadata

Use stable OMS IDs to identify records throughout their lifecycle. Names and display order should not be used as integration keys.

Suggested metadata conventions are:

These are proposed conventions, not predefined Koddi fields. Confirm metadata configuration and read/write support for each object with your Koddi team.

Keep a durable mapping table in the integration service containing the source IDs, execution key, Koddi environment, native Koddi IDs, last applied source version, and synchronization outcome. Use the supported Koddi metadata interfaces to persist external references alongside those mappings. Preserve unrelated metadata during updates.

Metadata stores the references. The integration service performs synchronization; native Koddi IDs establish relationships between Koddi objects.

Field Ownership

Assign an owner to every synchronized field before enabling updates in both directions.

A Koddi optimization should not silently rewrite the booked order. Similarly, replaying an unchanged order should not reset execution settings managed by Ad Ops.

Product and Inventory Mapping

An OMS product is a commercial description. Translate it into the Koddi configuration needed to fulfill the sale.

For each supported product, define the experience or channel, placement eligibility, targeting, pricing model, budget or delivery goal, flight rules, and creative requirements. Use agreed defaults for fields the OMS does not supply.

For example, a “Homepage Display” line may require a specific experience, eligible placements, a CPM, an impression commitment, and approved assets. A Sponsored Products line may require a spend budget, eligible entities, and bidding settings.

Keep budget, booked units, contracted rate, and delivery goals distinct. Do not translate a fixed fee or sponsorship into a CPC or CPM budget without agreed fulfillment and billing rules.

For reserved inventory, define which system owns availability checks, holds, confirmation, expiration, and release. Configure the reservation workflow with Koddi before booking reserved media. An OMS booking or metadata reference alone should not be treated as a confirmed inventory reservation.

Approved Order Workflow

Choose the OMS milestone that authorizes media setup, such as an approved or booked order. Proposal-stage synchronization can be added separately for planning, provided it cannot activate media.

Koddi’s Create Media Plan API accepts plan configuration, including budget, dates, experience allocations, and an IO reference. The media plan submission API creates associated campaigns and Ad Groups and reports successful campaigns and failed experiences.

Choose one creation path. If submission generates the child records, capture those IDs rather than independently creating another set. Record partial success before retrying failures.

For direct campaign configuration, use the applicable Campaign APIs. Validate the selected API version and required fields for your environment.

Commercial approval and activation are separate actions. Before activation, verify the required creative approvals, targeting, entity eligibility, funding, inventory commitments, and permissions. Order approval should not itself change media to an active state.

IO Associations and Budget Allocation

Associate every execution with the commercial authorization intended to fund it. One IO may govern several campaigns.

For example, a $100,000 order might authorize:

The example assumes the full order amount is executable media. If the order includes fees, discounts, or other charges, agree on the media allocation separately.

Validate allocations across all derived campaigns. Giving each campaign the full $100,000 would authorize more media than intended.

If Koddi can reallocate budgets between experiences, determine whether that flexibility is compatible with the OMS line commitments. Configure fixed allocations where the commercial agreement requires them.

Amendments and Cancellations

Process changes against existing mappings and retain the approved order history.

Use source versions or equivalent change controls to reject stale events. Record the amendment’s effective time, affected records, previous values, and outcome.

If one line spans multiple campaigns, apply the change to every affected execution and report incomplete updates. A cancellation is complete only when the intended delivery state has been confirmed.

Where an amendment requires a revised commercial agreement, keep it pending until the required approval is recorded. Use the integration’s approval process and supported APIs; confirm native revision functionality separately.

Reporting and Billing Reconciliation

Return delivery data at the grain required by the OMS, commonly order line and reporting date.

1. Retrieve delivery through the Reporting APIs or an agreed secure data collaboration pipeline.

2. Join native Koddi IDs to the OMS references in the mapping table and metadata.

3. Aggregate all executions fulfilling each commercial line.

4. Upsert the reporting rows in the OMS and retain the reporting timestamp.

5. Route missing mappings or reconciliation differences for review.

Typical outputs include spend, impressions, clicks, campaign state, and delivery against the approved commitment. Attributed conversions, sales, and ROAS can be included where configured.

Agree on reporting dimensions, metric definitions, currency, time zone, refresh frequency, and historical restatement windows. Use a stable reporting key, such as OMS tenant + order line + date + currency + execution system, with any additional dimensions required by the dataset.

Select a consistent reporting grain. Campaign totals and their underlying Ad Group totals describe overlapping delivery and should not be added together.

Booked Delivered and Billable Values

Keep these amounts separate:

For example, a $100,000 booking with $92,000 delivered does not automatically establish a $92,000 invoice. Fixed fees, guarantees, credits, complimentary media, overdelivery, and contractual adjustments can change the result.

Use a single designated invoicing process. Koddi’s invoicing options depend on the program’s agreement and configuration. If the OMS or ERP invoices the advertiser, align Koddi’s funding and invoicing setup with that process.

For orders spanning multiple execution platforms, include an execution-system identifier and reconcile only the Koddi portion from Koddi data. Obtain other platforms’ delivery separately.

Authentication and Operational Handling

Use credentials provisioned for the required Koddi environment and permissions. The Sessions documentation describes bearer authentication for protected management APIs. Manage token renewal server-side and keep credentials out of OMS metadata and logs.

The integration should:

• Resolve existing mappings before creating records, and serialize conflicting updates to the same order.

• Check whether a timed-out create succeeded before repeating it.

• Persist progress after each successful operation so interrupted workflows can resume.

• Retry transient failures with backoff; send invalid mappings or commercial conflicts to an exception queue.

• Track source versions, last successful synchronization, reporting freshness, and outstanding failures.

• Keep audit records linking the source order change to the Koddi request and confirmed result.

Agree on synchronization latency, monitoring ownership, escalation, and recovery procedures. Returning “received” to the OMS should be distinct from confirming that every Koddi update succeeded.

Implementation and Validation

Start with one product family and the minimum lifecycle: account mapping, approved order setup, explicit activation, delivery return, amendment, and cancellation. Expand after reconciliation is reliable.

Before development, agree on object mappings, field ownership, product translation, metadata interfaces, creation paths, IO associations, reservation responsibilities, reporting contracts, billing ownership, and support responsibilities.

Validate these acceptance checks in a test environment:

• A new order produces the intended advertiser mapping and media allocations.

• Existing advertisers and campaigns are reused when already mapped.

• Split order lines retain distinct execution keys and roll up correctly.

• Setup and order approval do not activate media.

• Replayed, out-of-order, timed-out, and partially failed operations do not create duplicates or overwrite newer changes.

• Amendments preserve prior commitments and apply only after required approval.

• Cancellations stop all intended executions and retain delivery history.

• OMS reporting reconciles to Koddi at the agreed grain without double counting.

• Billing adjustments remain distinguishable from delivered spend.

• Missing mappings and failed updates are visible and recoverable.

FAQ