5.315 min read

Order Management APIs

Order Management APIs form the runtime execution engine of a catalog-driven architecture. While catalog APIs define what is possible, order APIs capture what is actually happening. An order flows from the customer's request through product, service, and resource layers -- each managed by a dedicated API.

The order management chain consists of TMF622 (Product Ordering), TMF641 (Service Ordering), TMF652 (Resource Ordering), and TMF640 (Service Activation & Configuration). These APIs work in concert to decompose a high-level customer request into network-level actions.

Order Decomposition Pattern

In TM Forum architecture, orders cascade through layers. A single ProductOrder may generate multiple ServiceOrders, and each ServiceOrder may generate multiple ResourceOrders. This decomposition is driven by the catalog specifications -- the same catalog entries that define the product structure also define the fulfilment requirements.

TMF622: Product Ordering

TMF622 -- Product Ordering

TMF622 manages the capture and lifecycle of product orders -- the requests from customers to add, modify, or remove products from their subscription. It is the primary API consumed by digital channels, agent desktops, and partner portals to submit customer orders.

A product order contains one or more ProductOrderItems, each representing a specific action (add, modify, delete, noChange) on a product. Each order item references a ProductOffering (from TMF620) and may include product characteristics, related services, and delivery details.

TMF622 Key Resources

TMF622 Core Resources

Resource	Purpose	Key Attributes
ProductOrder	A customer request to add/modify/delete products	externalId, state, orderDate, requestedStartDate, requestedCompletionDate, productOrderItem, relatedParty, channel, note
ProductOrderItem	A single line item within an order	action (add/modify/delete/noChange), productOffering, product, state, quantity, itemPrice, orderItemRelationship
CancelProductOrder	A request to cancel a pending order	productOrder, cancellationReason, state, requestedCancellationDate

Product Order State Machine

TMF622 defines a standard state machine for product orders. Understanding these states is essential for building order tracking UIs and integration logic.

TMF622 Order States

State	Meaning	Typical Trigger
Acknowledged	Order received and validated	POST /productOrder succeeds
InProgress	Order is being fulfilled (service/resource orders created)	Fulfilment processing begins
Pending	Order is waiting for external input (e.g., site survey)	Manual task or external dependency
Held	Order is temporarily paused (e.g., credit check failed)	Business rule or manual hold
Completed	All order items successfully fulfilled	All child orders complete
Failed	Order could not be fulfilled	Critical fulfilment error
Partial	Some order items completed, some failed	Mixed fulfilment results
Cancelled	Order cancelled before completion	CancelProductOrder request processed
CancellationInProgress	Cancellation is being processed (rollback in progress)	CancelProductOrder request received

Order Item Actions

The "action" field on ProductOrderItem is critical for modify and cease scenarios. "add" creates a new product instance. "modify" changes an existing product (e.g., speed upgrade). "delete" removes a product (cease). "noChange" means the item is included for context but no action is needed (common in bundle modifications where only one item changes).

TMF641: Service Ordering

TMF641 -- Service Ordering

TMF641 manages service-level orders -- the requests to add, modify, or remove service instances. Service orders are typically generated by the product order management system (not directly by customers) and processed by Service Order Management (SOM) for orchestration and fulfilment.

A service order is the bridge between the commercial intent (product order) and the technical execution (resource orders and activation). SOM reads the service catalog (TMF633) to decompose the service order into individual service actions and downstream resource requirements.

TMF641 Key Resources

TMF641 Core Resources

Resource	Purpose	Key Attributes
ServiceOrder	A request to fulfil service-level actions	externalId, state, orderDate, serviceOrderItem, relatedParty, note
ServiceOrderItem	A single service action within the order	action (add/modify/delete/noChange), service, state, serviceOrderItemRelationship

The service order item's service attribute contains the service instance data, including the serviceSpecification reference and serviceCharacteristic values that define what needs to be provisioned.

Service Order State Machine

TMF641 uses a state machine very similar to TMF622, applied at the service level:

Acknowledged -- Service order received and validated against service catalog
InProgress -- SOM is orchestrating fulfilment (resource orders created, activation in progress)
Completed -- All service order items successfully fulfilled and service instances updated
Failed -- Service fulfilment failed (reported back to product order management)
Partial -- Some service items succeeded, others failed
Held -- Awaiting manual intervention or external dependency
Cancelled -- Service order cancelled

TMF652: Resource Ordering

TMF652 -- Resource Ordering

TMF652 manages resource-level orders -- the requests to allocate, configure, or release specific network resources. Resource orders are typically generated by the service order management system and processed by Resource Order Management (ROM) or directly by activation/provisioning systems.

Resource orders are the lowest-level orders in the chain. They deal with concrete network actions: allocate a VLAN, assign an IP address, configure a port, deploy a VNF. The resource catalog (TMF634) defines what types of resources can be ordered.

TMF652 Key Resources

TMF652 Core Resources

Resource	Purpose	Key Attributes
ResourceOrder	A request to allocate/configure/release resources	externalId, state, orderDate, resourceOrderItem, relatedParty, note
ResourceOrderItem	A single resource action within the order	action (add/modify/delete/noChange), resource, state, resourceOrderItemRelationship

Resource Order for Broadband Provisioning

A service order for CFS:Internet-Access might generate three resource order items: (1) action:add for a GPON port allocation on the nearest OLT, (2) action:add for a VLAN assignment, (3) action:add for an IP address from the local pool. Each item references the specific ResourceSpecification from TMF634 and includes the characteristic values (e.g., VLAN ID: 1042, IP: 10.42.1.15/24).

TMF640: Service Activation & Configuration

TMF640 -- Service Activation & Configuration

TMF640 provides an API for activating and configuring services on the network. It is the "last mile" of fulfilment -- the point where logical service definitions become real network configurations. TMF640 is used by SOM or ROM to trigger activation on the network equipment.

TMF640 works with service instances (from TMF638). It takes a service that has been designed and configured, and activates it on the actual network. This may involve pushing configurations to network elements, activating ports, enabling QoS profiles, or instantiating virtual network functions.

Intermediate

Activation vs Configuration

Activation makes a service operational (turns it "on"). Configuration sets the parameters of how it operates. TMF640 covers both: you might configure a service first (set parameters) and then activate it (make it live).

In practice, the distinction matters for modify orders. A speed upgrade might only require re-configuration (change the QoS profile parameters) without deactivation/reactivation. A technology migration might require full deactivation on the old platform and activation on the new one.

How Orders Flow Through the API Chain

The following step flow traces a customer order from initial capture through to network activation, showing how each API hands off to the next.

End-to-End Order Flow

Order Capture (TMF622)

COM -- Product Order Management

Customer or agent submits a product order via TMF622. The order is validated against the product catalog (TMF620) and enters "Acknowledged" state.

Order Decomposition

COM -- Order Decomposition Engine

COM reads the product specification from TMF620, identifies the linked CFS from TMF633, and creates a service order via TMF641 with the required CFS and RFS items.

Service Orchestration (TMF641)

SOM -- Service Order Management

SOM receives the service order, reads decomposition rules from TMF633, and creates resource orders via TMF652 for each required resource allocation.

Resource Fulfilment (TMF652)

ROM -- Resource Order Management

ROM receives resource orders and orchestrates resource allocation (e.g., VLAN assignment, port reservation) against the resource inventory (TMF639).

Activation (TMF640)

Activation / Provisioning System

Once resources are allocated, TMF640 triggers activation on the network. Configurations are pushed to network elements. The service transitions to "Active" state.

Inventory Update

Inventory Systems

Service inventory (TMF638) and resource inventory (TMF639) are updated with the new active instances. Product inventory (TMF637) records the customer's active product.

Order Completion (TMF622)

COM -- Product Order Management

Status propagates back up the chain: ResourceOrder -> Completed, ServiceOrder -> Completed, ProductOrder -> Completed. The customer is notified.

Order Lifecycle Events

Each order API publishes events as orders progress through their lifecycle. These events are essential for building reactive, loosely coupled integrations between order management layers.

Key Order Events

API	Event	Purpose
TMF622	ProductOrderCreateEvent	New product order submitted
TMF622	ProductOrderStateChangeEvent	Order state transitions (e.g., InProgress -> Completed)
TMF622	ProductOrderAttributeValueChangeEvent	Order attribute modified (e.g., requested completion date)
TMF641	ServiceOrderCreateEvent	New service order created (by COM)
TMF641	ServiceOrderStateChangeEvent	Service order state transitions
TMF652	ResourceOrderCreateEvent	New resource order created (by SOM)
TMF652	ResourceOrderStateChangeEvent	Resource order state transitions

Event-Driven Order Tracking

Rather than polling each order API for status updates, systems should subscribe to state change events. When TMF652 publishes ResourceOrderStateChangeEvent with state=Completed, SOM can immediately update its service order. When TMF641 publishes ServiceOrderStateChangeEvent with state=Completed, COM can complete the product order. This event chain eliminates polling delays and reduces API load.

Order Modifications and Cancellations

A modify order changes an existing product -- for example, upgrading broadband speed from 100Mbps to 500Mbps. A cancel order stops a pending order before it completes. Both are common scenarios that the order APIs must handle gracefully.

A modify order in TMF622 uses action="modify" on the ProductOrderItem and references the existing product instance (from TMF637). The order includes only the changed characteristics. The downstream chain must determine what actually needs to change:

Speed upgrade: may only require RFS parameter change and QoS reconfiguration (no new resources)
Technology migration (e.g., DSL to Fibre): requires new CFS/RFS decomposition, new resource allocation, and decommissioning of old resources
Bundle change (add TV to broadband): requires adding new CFS/RFS instances while keeping existing ones

TMF622 provides a CancelProductOrder resource for requesting cancellation. The complexity depends on how far the order has progressed:

If the order is still in "Acknowledged" state, cancellation is straightforward -- discard the order
If resource orders are already "InProgress", ROM must release any partially allocated resources
If activation has occurred, a compensating deactivation must be triggered via TMF640
Each layer must handle its own rollback and propagate the cancellation status back up the chain
Idempotency of cancellation requests is critical -- systems must handle duplicate cancel requests gracefully

Comparing Order Management APIs

Order API Comparison

Aspect	TMF622 (Product)	TMF641 (Service)	TMF652 (Resource)
Domain	BSS -- Commercial	OSS -- Service	OSS -- Resource
Created by	Customer / Agent / Channel	Product Order Management	Service Order Management
Processed by	COM (Commercial Order Mgmt)	SOM (Service Order Mgmt)	ROM (Resource Order Mgmt)
References catalog	TMF620 (Product Catalog)	TMF633 (Service Catalog)	TMF634 (Resource Catalog)
Updates inventory	TMF637 (Product Inventory)	TMF638 (Service Inventory)	TMF639 (Resource Inventory)
Item actions	add, modify, delete, noChange	add, modify, delete, noChange	add, modify, delete, noChange
Pricing included	Yes (itemPrice)	No	No
Customer-visible	Yes -- trackable by customer	Internal to telco	Internal to telco

Order API Source of Record

Order Entities -- Source of Record

Entity	System of Record	System of Engagement	System of Reference	Notes
Product Orders	COM / Order Management (TMF622)	Digital Channel / Agent Desktop	—	Customer-facing order lifecycle
Service Orders	SOM (TMF641)	COM (creates them)	—	Service-level fulfilment tasks
Resource Orders	ROM (TMF652)	SOM (creates them)	—	Resource-level allocation tasks
Order State	Respective order management system	Order tracking UI	—	Each layer owns its own state machine

Common Order Management Anti-Patterns

Anti-Pattern: Skipping the Service Layer

Some implementations bypass TMF641 and go directly from product orders (TMF622) to resource orders (TMF652). This creates tight coupling between commercial and resource layers, makes technology migrations difficult, and eliminates the ability to reuse service decomposition logic across products. Always maintain the service layer as a mediation point.

Anti-Pattern: Synchronous Order Chains

Making the entire order chain synchronous (TMF622 waits for TMF641, which waits for TMF652, which waits for TMF640) creates brittle, long-running transactions. If any step hangs, the entire chain blocks. Use asynchronous event-driven patterns: submit the order, return immediately, and notify via events when state changes occur.

Anti-Pattern: Monolithic Order Items

Cramming all service and resource details into the product order item (TMF622) instead of letting each layer manage its own concerns violates separation of concerns. The product order should contain commercial intent only; service and resource details belong in their respective orders.

Section 5.3 Key Takeaways

TMF622 captures commercial intent (what the customer wants); TMF641 handles service fulfilment; TMF652 handles resource allocation
Orders cascade: Product Order -> Service Order -> Resource Order -> Activation
Each order API has a standard state machine (Acknowledged -> InProgress -> Completed/Failed)
Order item actions (add/modify/delete/noChange) determine the fulfilment behaviour at each layer
TMF640 handles the final step: pushing configurations to the network and activating services
Event-driven patterns (not synchronous chains) are the recommended integration approach
Each layer owns its own state machine and should not expose internal details to other layers
Always maintain the service layer (TMF641) as a mediation point between commercial and resource orders