API Reference Cards: When to Use & Common Misuses

API Reference Cards

This section provides a structured reference card for each of the six most critical TM Forum Open APIs in a BSS/OSS architecture. For each API, the card specifies its purpose, domain ownership, correct use cases, anti-patterns (when NOT to use it), and the most common implementation mistakes observed in real-world deployments.

Use these cards during architecture reviews, vendor evaluations, and integration design to ensure each API is being applied correctly. Misuse of TM Forum APIs is one of the most common causes of integration failure — not because the APIs are flawed, but because they are used in the wrong context or with incorrect assumptions.

TMF620 — Product Catalog Management

When to Use TMF620

• CPQ reading the catalog: CPQ queries TMF620 to retrieve available Product Offerings, their characteristics, pricing rules, and eligibility constraints for a given customer and channel.
• Self-service portal browsing products: Digital channels use TMF620 to present the product catalog to customers, including category navigation, product comparison, and pricing display.
• COM validating orders: COM queries TMF620 to validate that an ordered product exists, is in an active lifecycle state, and that the configured characteristics are within allowed values.
• SOM resolving decomposition rules: SOM queries TMF620 to find the Product Specification's linked CFS specifications, which drive the product-to-service decomposition.
• Billing loading pricing rules: Billing reads pricing components from TMF620 to apply the correct tariffs and discounts when rating usage or generating invoices.
• Product lifecycle management: Product managers use TMF620 to create, modify, retire, and obsolete Product Offerings through formal lifecycle state transitions.

When NOT to Use TMF620

• Do NOT use TMF620 for product instances — TMF620 is design-time (what CAN be sold). For runtime records of what a customer HAS, use TMF637 (Product Inventory). Confusing catalog with inventory is the single most common TMF API mistake.
• Do NOT use TMF620 for service or resource catalogs — Product Catalog is commercial. Use TMF633 for Service Catalog and TMF634 for Resource Catalog. Each catalog has distinct semantics and ownership.
• Do NOT use TMF620 for order capture — TMF620 is a read-mostly API for catalog queries. To create orders, use TMF622 (Product Ordering). Do not extend TMF620 with order-like operations.
• Do NOT use TMF620 as a master data hub — TMF620 manages product definitions, not customer data, account data, or pricing engine logic. It should not become a catch-all for non-product commercial data.

Common TMF620 Misuses

TMF622 — Product Ordering

When to Use TMF622

• Channel-to-COM order submission: All channels (web, mobile, retail, partner, B2B) submit Product Orders to COM via TMF622. This is the standard inbound interface for order capture.
• COM-to-SOM handoff: COM uses TMF622 events or a derived TMF641 call to pass validated orders to SOM for service-level fulfilment. TMF622 represents the commercial intent that SOM must decompose.
• Order status tracking: Channels and CRM query TMF622 to track order progress, retrieve current state, and display fulfilment updates to customers and agents.
• Order amendment and cancellation: TMF622 supports in-flight order modification via the CancelProductOrder resource and order item updates. This is used for customer-requested changes before fulfilment completes.
• B2B partner ordering: Wholesale and partner channels use TMF622 as a machine-to-machine interface for automated order submission, following the same payload structure as internal channels.

When NOT to Use TMF622

• Do NOT use TMF622 for service-level ordering — TMF622 operates at the Product (commercial) level. For service-level fulfilment, use TMF641 (Service Ordering). Sending TMF622 payloads directly to SOM bypasses the decomposition step.
• Do NOT use TMF622 for resource provisioning — TMF622 is commercial, not technical. For resource-level ordering, use TMF652 (Resource Ordering). Sending product orders directly to ROM violates the three-layer model.
• Do NOT use TMF622 for quoting — TMF622 creates orders that trigger fulfilment. For quotes (non-binding proposals), use TMF648 (Quote Management). Creating TMF622 orders as "draft quotes" pollutes the order pipeline.
• Do NOT use TMF622 for product browsing — TMF622 is a transactional API for order creation. For catalog browsing and product discovery, use TMF620 (Product Catalog).

Common TMF622 Misuses

TMF633 — Service Catalog Management

When to Use TMF633

• SOM resolving decomposition rules: SOM queries TMF633 to determine how a ProductSpecification decomposes into CFS instances, and how each CFS further decomposes into RFS instances and resource requirements.
• Service design and onboarding: Service architects use TMF633 to publish new CFS and RFS specifications, including their characteristics, relationships, dependencies, and lifecycle states.
• Product-to-service linkage: TMF633 ServiceSpecifications are linked from TMF620 ProductSpecifications, creating the catalog chain that drives automated decomposition.
• Service qualification: Service qualification systems query TMF633 to determine which services are available at a given location by checking CFS specifications against coverage and capability data.

When NOT to Use TMF633

• Do NOT use TMF633 for service instances — TMF633 is design-time (service definitions). For runtime instances of active services, use TMF638 (Service Inventory). This is the service-layer equivalent of the TMF620/TMF637 distinction.
• Do NOT use TMF633 for product definitions — Service specifications describe technical service types, not commercial products. Use TMF620 for product offerings and specifications.
• Do NOT use TMF633 for resource specifications — Resource types (equipment models, port types, VLAN ranges) belong in TMF634 (Resource Catalog), not TMF633.
• Do NOT use TMF633 for orchestration logic — TMF633 defines WHAT services exist and HOW they decompose. It does not define the orchestration SEQUENCE (which tasks run in parallel vs sequentially). Orchestration sequencing is a SOM concern.

Common TMF633 Misuses

TMF637 — Product Inventory Management

When to Use TMF637

• CRM displaying "what the customer has": Agent desktops and self-service portals query TMF637 to show the customer's active products, subscriptions, and their current characteristics.
• COM handling modify/cease orders: Before processing a modification or cessation order, COM queries TMF637 to retrieve the current product instance and calculate the delta between current and target state.
• Billing reconciliation: Billing queries TMF637 to verify that charges align with active products. Revenue assurance uses TMF637 as the reference for what should be billed.
• COM updating on fulfilment completion: When fulfilment completes, COM creates or updates product instances in TMF637 to reflect the new subscription state.
• Cross-sell/up-sell analysis: Analytics systems query TMF637 to identify product holdings, enabling targeted cross-sell and up-sell recommendations.

When NOT to Use TMF637

• Do NOT use TMF637 for product definitions — TMF637 manages product INSTANCES (what a customer has). For product DEFINITIONS (what can be sold), use TMF620 (Product Catalog).
• Do NOT use TMF637 for service or resource instances — Product Inventory is commercial. For service instances (CFS/RFS), use TMF638. For resource instances, use TMF639. These are separate inventories with different ownership.
• Do NOT use TMF637 for order tracking — TMF637 tracks the current state of products, not the order that created them. For order lifecycle tracking, use TMF622.
• Do NOT use TMF637 as a billing system — Product Inventory tracks what exists; billing tracks what is charged. They should be separate systems with TMF637 informing billing, not replacing it.

Common TMF637 Misuses

TMF638 — Service Inventory Management

When to Use TMF638

• SOM creating service instances on activation: When fulfilment completes, SOM creates CFS and RFS instances in TMF638 to record the active service configuration.
• Fault correlation (resource → service → customer): Assurance systems query TMF638 to determine which CFS instances are affected by a resource fault, and then trace from CFS to Product Inventory to identify affected customers.
• Service qualification: Pre-order feasibility checks query TMF638 to determine if existing service instances can be reused or upgraded, or if a new service instance is required.
• Capacity planning: Planning systems query TMF638 to understand service utilisation patterns and forecast future capacity needs.
• Modify/cease flow delta calculation: SOM queries TMF638 to retrieve the current service configuration and calculate what changes are needed for a modification order.

When NOT to Use TMF638

• Do NOT use TMF638 for service definitions — TMF638 manages service INSTANCES (what is running). For service DEFINITIONS (CFS/RFS specifications), use TMF633 (Service Catalog).
• Do NOT use TMF638 for resource instances — Service Inventory tracks services, not resources. For physical and logical resource instances, use TMF639 (Resource Inventory). TMF638 links TO resources via supportingResource, but does not manage them.
• Do NOT use TMF638 for product instances — Service instances are technical (OSS). For commercial product instances (subscriptions), use TMF637 (Product Inventory).
• Do NOT use TMF638 for network monitoring — TMF638 holds the inventory record of services, not real-time performance data. For service quality monitoring, use TMF656 (Service Problem) or dedicated monitoring tools.

Common TMF638 Misuses

TMF640 / TMF641 — Service Activation & Service Ordering

When to Use TMF641 / TMF640

• COM-to-SOM order handoff (TMF641): COM submits service orders to SOM via TMF641 after decomposing the product order into CFS-level items. This is the primary BSS-to-OSS integration point for fulfilment.
• SOM orchestrating fulfilment (TMF641): SOM uses TMF641 internally to manage the service order lifecycle, track item states, and coordinate dependencies between service order items.
• SOM-to-ROM decomposition (TMF641 → TMF652): SOM decomposes service order items into resource order items and submits them to ROM via TMF652. TMF641 events report service-level progress back to COM.
• Pushing service configuration (TMF640): The activation component uses TMF640 to push service-specific configuration to service platforms (e.g., policy controllers, DNS servers, authentication systems).
• Service modification flows (TMF641): For modify orders, SOM creates TMF641 service orders with "modify" action items, specifying the delta between current and target service configuration.

When NOT to Use TMF641 / TMF640

• Do NOT use TMF641 for commercial order capture — TMF641 is for service-level fulfilment, not commercial order capture. Use TMF622 (Product Ordering) for customer-facing order submission.
• Do NOT use TMF641 for resource provisioning — TMF641 operates at the service layer. For resource-level provisioning (port allocation, VLAN assignment, device configuration), use TMF652 (Resource Ordering).
• Do NOT use TMF640 for network element configuration — TMF640 is for service-platform-level activation. For direct network element configuration (router, switch, OLT), use NETCONF, CLI adapters, or TMF652 with activation adapters.
• Do NOT use TMF641 for trouble ticket creation — Even though service problems may trigger automated remediation, trouble tickets should be created via TMF621 (Trouble Ticket), not as TMF641 service orders.

Common TMF641/640 Misuses

Cross-API Quick Reference

The following table summarises the design-time vs runtime distinction and the ownership boundaries across all six key APIs. This is the most common source of confusion in TMF API adoption.