FIT Product Ordering Management API

AG-FIT 622

Release Value

Version

2.0.4

Date

2026-09-01

State

pre-released

Description

The Product Ordering Management API provides a standardized mechanism for placing and managing product orders between customers, service providers, and partners. It includes task resources for changes to orders and lifecycle notifications.

See Auftrag (Neu) anlegen for sample use cases.

FIT adaptations

The FIT profile is based on the TM Forum Product Ordering Management API and applies FIT-specific adaptations to operations, lifecycle information, and the Product Order resource model.

The following adaptations are relevant for FIT implementations:

  • PATCH and DELETE operations on ProductOrder are not used in the FIT profile.

  • Product Order state changes are represented through state-change history information.

  • Milestone and jeopardy handling is adapted to the requirements of the FIT order lifecycle.

  • ProviderChangeInfo is added to represent changes initiated or proposed by the provider.

  • requestedTimeSlot is used to represent the requested scheduling information for an order or order item.

  • alternateProductOffering supports alternative product offerings where applicable.

  • The InflightChangeProductOrder task resource is added to support changes to an already submitted Product Order.

  • The CancelProductOrder task resource provides the FIT mechanism for requesting cancellation of an existing Product Order.

The complete FIT-specific resource definitions and supported operations are documented in the API reference.

Managed entity resource model

Product Order

A Product Order places an order between a customer, service provider, or partner.

Lifecycle

Product Order lifecycle

Resource model

product-order-resource

JSON representation sample

{
  "$schema" : "../schema/fit-tmf622.schema.json",
  "@type" : "ProductOrder",
  "id" : "388a4963-f168-4603-99e8-477200099d91",
  "href" : "https://api.example.org/tmf-api/productOrderingManagement/v5/productOrder/388a4963-f168-4603-99e8-477200099d91",
  "category" : "new",
  "creationDate" : "2022-05-11T10:30:30+02:00",
  "orderPostedDate" : "2022-05-11T10:30:00+02:00",
  "requestedCompletionDate" : "2022-12-01T12:00:00+01:00",
  "agreement" : [ {
    "@type" : "Agreement",
    "name" : "buyerServiceContract",
    "engagedParty" : [ {
      "@type" : "Organization",
      "businessId" : "500011"
    } ],
    "businessId" : "500012",
    "agreementType" : "buyerServiceContract"
  }, {
    "@type" : "Agreement",
    "name" : "ordererServiceContract",
    "engagedParty" : [ {
      "@type" : "Organization",
      "businessId" : "500014"
    } ],
    "businessId" : "500013",
    "agreementType" : "ordererServiceContract"
  }, {
    "@type" : "Agreement",
    "name" : "providerChangeAgreement",
    "businessId" : "DEU.VFD.V012345678",
    "agreementType" : "providerChangeAgreement"
  } ],
  "externalId" : [ {
    "@type" : "ExternalIdentifier",
    "id" : "1000111",
    "externalIdentifierType" : "externalOrderId",
    "owner" : "DEU.VFD"
  } ],
  "billingAccount" : {
    "@type" : "BillingAccountRef",
    "id" : "5793126789"
  },
  "note" : [ {
    "@type" : "InstallationInstruction",
    "text" : "zweimal klingeln"
  } ],
  "productOrderItem" : [ {
    "@type" : "ProductOrderItem",
    "id" : "1",
    "action" : "add",
    "product" : {
      "@type" : "BitstreamAccessProduct",
      "creationDate" : "2022-05-11T10:30:30+02:00",
      "relatedPlace" : [ {
        "@type" : "RelatedPlaceRefOrValue",
        "role" : "locationA",
        "place" : {
          "@type" : "GeographicAddress",
          "city" : "Rheinhausen",
          "country" : "DE",
          "locality" : "Nordstadt",
          "postcode" : "59055",
          "streetName" : "Biberweg",
          "streetNr" : "2",
          "streetNrSuffix" : "a",
          "geographicSubAddress" : [ {
            "@type" : "GeographicSubAddress",
            "buildingName" : "Einfamilienhaus"
          } ]
        }
      } ],
      "networkTerminationUnitLocation" : "Flur 3.OG",
      "homeId" : "a12d5a4545"
    },
    "productOffering" : {
      "@type" : "ProductOffering",
      "name" : "FTTH 250000"
    },
    "requestedTimeSlot" : {
      "@type" : "TimeSlot",
      "validFor" : {
        "startDateTime" : "2022-12-01T08:00:00+01:00",
        "endDateTime" : "2022-12-01T12:00:00+01:00"
      }
    }
  } ],
  "relatedParty" : [ {
    "@type" : "RelatedPartyOrPartyRole",
    "role" : "orderManagementBuyerContact",
    "partyOrPartyRole" : {
      "@type" : "Individual",
      "contactMedium" : [ {
        "@type" : "PhoneContactMedium",
        "contactType" : "fixed",
        "phoneNumber" : "+49221456789"
      }, {
        "@type" : "PhoneContactMedium",
        "contactType" : "mobile",
        "phoneNumber" : "+4917754545454"
      }, {
        "@type" : "EmailContactMedium",
        "contactType" : "email",
        "emailAddress" : "j.kirk@example.net"
      } ],
      "familyName" : "Kirk",
      "salutation" : "Herr",
      "givenName" : "James T.",
      "title" : "Captain"
    }
  }, {
    "@type" : "RelatedPartyOrPartyRole",
    "role" : "installationContact",
    "partyOrPartyRole" : {
      "@type" : "Individual",
      "contactMedium" : [ {
        "@type" : "PhoneContactMedium",
        "contactType" : "fixed",
        "phoneNumber" : "+49221145155"
      }, {
        "@type" : "PhoneContactMedium",
        "contactType" : "mobile",
        "phoneNumber" : "+4917878878788"
      }, {
        "@type" : "EmailContactMedium",
        "contactType" : "email",
        "emailAddress" : "a.fischer@example.net"
      } ],
      "familyName" : "Fischer",
      "salutation" : "Herr",
      "givenName" : "Alexander"
    }
  }, {
    "@type" : "RelatedPartyOrPartyRole",
    "role" : "locationAContact",
    "partyOrPartyRole" : {
      "@type" : "Individual",
      "familyName" : "Müller",
      "salutation" : "Herr",
      "givenName" : "Maximilian"
    }
  } ],
  "state" : "acknowledged",
  "stateChangeDate" : "2022-05-11T10:30:00+02:00",
  "additionalOrderInformation" : {
    "campaignIdentifier" : [ "PromotionFiber" ],
    "projectIdentifier" : "AB1234",
    "couplingIdentifier" : "QW567",
    "orderBindingId" : "AK45678",
    "orderBindingNumberOfOrders" : 5,
    "hardwareIdType" : "ontSerialNumber",
    "hardwareIdValue" : "53674F3DC03FD37C"
  }
}

Task resource models

Lifecycle

Task resource lifecycle

Task lifecycle states

Cancel Product Order

cancel-product-order-resource

Inflight Change Product Order

inflight-change-product-order-resource

The task category identifies operations such as adding information, activating, amending, closing, responding to a provider change, or rescheduling.

Notifications

The API reference documents create, state-change, attribute-value-change, information-required, jeopardy-alert, and milestone events, including task-resource state changes.

Open the complete API reference

Authentication

This API is secured using OAuth 2.0. For machine-to-machine communication, it uses the Client Credentials flow. The authorization server issues an access token that the client uses to access protected API resources without sharing its credentials with the resource server.

oauthclientcredentialflow-puml

See Security schemes for the API-specific OAuth 2.0 configuration and FIT API authentication for the common authentication requirements.

Validation using the conformance profile

The conformance profile defines which attributes, structures, and constraints are applicable to the FIT implementation of TMF622. It can be used to validate Product Order payloads for compliance with the FIT specification.

The following artifacts are provided for validation and reference:

  • JSON Schema – machine-readable schema for automated validation of JSON payloads.

  • Excel – human-readable overview of the supported attributes, structures, and conformance requirements.

Supporting files