Skip to content

Service Ordering Using the API

Intended Audience: OpenSlice Users

Having covered how OpenSlice can facilitate the Service Design and exposure, this section introduces the process of ordering the designed Service Specifications and their fulfillment process.

To that extend, we assume that the OpenSlice Service Designers have already created the designated, detailed Service Specifications that are willing to expose to the OpenSlice users, or to potential Communication Service Customers (CSCs). Furthermore, the designed Service Specifications are categorized in the respective Service Categories and Catalogs.

Service Order UI vs API

While the Service Portal UI guides users through a visual step-by-step wizard, the Service Order API is designed for speed and automation.

The primary difference lies in discovery:

  • UI Users: Are guided by menus and visual categories to find what they need.

  • API Users: Are expected to know the specific Service Specification they intend to order before hitting the endpoint.

Not sure which ID to use? If you are integrating a new service and don't have the specification details yet, you can use the discovery flow to programmatically find the right specifications:

1) Query Service Catalogs: Retrieve the high-level list of available catalogs.

2) Filter by Category: Narrow down the functional area (e.g., "Cloud Connectivity" or "Security").

3) Identify the Specification: Extract the unique ID and requirements for your desired service.

The Anatomy of a Service Order API call

To successfully place an order via API, your POST request must contain the "essence" of the service. At a minimum, your payload should include:

Attribute Requirement Description
Service Specification ID Required The unique UUID of the Service Specification.
Name Required A human-readable label for the specific service instance.
Characteristics Optional Key-value pairs for configurable traits (e.g., bandwidth: 100Mbps).

Issue a Service Order

Prerequisites

  • Authentication: You must include a valid Bearer Token in the header. See the OAuth Setup Guide.
  • Service Specification ID: You should have the Service Specification ID ready. If you don't have it, query the Service Catalog first.

Endpoint Details

  • Method: POST
  • Endpoint: {URL}/tmf-api/serviceOrdering/v4/serviceOrder
  • Headers: Authorization: Bearer {{access_token}}

Request Payload Breakdown

The payload defines what is being ordered, how it is configured, and when it should be active.

An example:

{
  "orderItem": [
    {
      "service": {
        "serviceSpecification": {
          "id": "dcbc9ed6-bf01-41cc-9c0c-3fe4e2788a77",
          "name": "5G Connectivity and Internet Access"
        },
        "serviceCharacteristic": [
          {
            "name": "5G Radio Nodes",
            "valueType": "SET",
            "value": {
              "value": "[{\"value\":\"outdoor\",\"alias\":\"Outdoor Radio Units\"}]"
            }
          },
          {
            "name": "MCC",
            "valueType": "TEXT",
            "value": {
              "value": "001",
              "alias": ""
            }
          },
          {
            "name": "MNC",
            "valueType": "TEXT",
            "value": {
              "value": "01",
              "alias": null
            }
          },
          {
            "name": "TAC",
            "valueType": "TEXT",
            "value": {
              "value": "100",
              "alias": null
            }
          },
          {
            "name": "RAN Profile",
            "valueType": "ENUM",
            "value": {
              "value": "1",
              "alias": "Default"
            }
          }
        ]
      },
      "action": "add",
      "state": "ACKNOWLEDGED"
    }
  ],
  "requestedStartDate": "2026-01-01T09:00:00.000Z",
  "requestedCompletionDate": "2026-01-02T09:00:00.000Z"
}

Payload breakdown:

  • serviceSpecification.id: The unique identifier for the Service Specification.
  • serviceSpecification.name: The human-readable name of the specification.
  • service.serviceCharacteristics: (Optional) An array with optional configurable characteristics for your service
    • valueType: Defines the data format (e.g., SET, TEXT, ENUM).
    • value.value: The desired value of the characteristic.

      For types SET or ARRAY, the value property must be a stringified JSON object. Ensure you escape quotes correctly as shown in the example.

    • value.alias: (Optional) Used to provide a user-friendly name in the UI
  • service.action: Set to "add" for all new service provisions.
  • service.state: Controls the automation workflow.
    • ACKNOWLEDGED: Fully automated. Fulfillment begins immediately.
    • INITIAL: Manual intervention required. An operator (Admin User) must confirm the order in OpenSlice, setting it to "ACKNOWLEDGED".
  • service.requestedStartDate: When the service should be provisioned (ISO 8601).
  • service.requestedCompletionDate: When the service should be automatically decommissioned (Teardown).

    If you use a past date, the service will decommission right after deployment. Ensure the proper provision of dates.

Service Order Request Response

The above request, will return a respective response:

{
  "uuid": "2121a09c-0de1-4854-aa7e-d7deb5571c1c",
  "orderDate": "2026-01-01T08:00:00.000Z",
  "completionDate": null,
  "expectedCompletionDate": "2026-01-02T09:00:00.000Z",
  "requestedCompletionDate": "2026-01-02T09:00:00.000Z",
  "requestedStartDate": "2026-01-01T09:00:00.000Z",
  "startDate": "2026-01-01T09:00:00.000Z",
  "@baseType": "BaseRootEntity",
  "@schemaLocation": null,
  "@type": "ServiceOrder",
  "href": null,
  "id": "2121a09c-0de1-4854-aa7e-d7deb5571c1c",
  "category": null,
  "description": null,
  "externalId": null,
  "notificationContact": null,
  "priority": null,
  "note": [
    {
      "uuid": "4621cb9a-b0d3-469a-b903-701f41ed1b0d",
      "date": "2023-07-21T13:19:20.877630603Z",
      "@baseType": "BaseEntity",
      "@schemaLocation": null,
      "@type": null,
      "href": null,
      "author": "SO641API-addServiceOrder",
      "system": null,
      "text": "Service Order INITIAL"
    }
  ],
  "orderItem": [
    {
      "uuid": "0745fd3d-5f6a-4118-ad54-fadad111ca47",
      "@baseType": "BaseEntity",
      "@schemaLocation": null,
      "@type": null,
      "href": null,
      "id": "0745fd3d-5f6a-4118-ad54-fadad111ca47",
      "action": "add",
      "orderItemRelationship": [],
      "state": "ACKNOWLEDGED",
      "service": {
        "uuid": "bc474ff9-d838-42be-9431-a25e1ab78b1b",
        "serviceSpecification": {
          "@baseType": "BaseEntity",
          "@schemaLocation": null,
          "@type": null,
          "href": null,
          "name": "5G Connectivity and Internet Access",
          "version": "0.1.0",
          "targetServiceSchema": null,
          "@referredType": null,
          "id": "dcbc9ed6-bf01-41cc-9c0c-3fe4e2788a77"
        },
        "@baseType": "BaseEntity",
        "@schemaLocation": null,
        "@type": null,
        "href": null,
        "name": "5G Connectivity and Internet Access",
        "id": "bc474ff9-d838-42be-9431-a25e1ab78b1b",
        "category": null,
        "serviceType": null,
        "place": [],
        "relatedParty": [],
        "serviceCharacteristic": [
          {
            "uuid": "bd2c34ff-604a-49e8-adfc-5f4dc8b9f57e",
            "value": {
              "value": "[{\"value\":\"outdoor\",\"alias\":\"Outdoor Radio Units\"}]",
              "alias": null
            },
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "5G Radio Nodes",
            "valueType": "SET"
          },
          {
            "uuid": "d90f4e4e-f924-4421-8363-24f30dfa225b",
            "value": {
              "value": "01",
              "alias": null
            },
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "MNC",
            "valueType": "TEXT"
          },
          {
            "uuid": "5dac7869-8a63-409e-9dad-f331a4f0e3ce",
            "value": {
              "value": "100",
              "alias": null
            },
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "TAC",
            "valueType": "TEXT"
          },
          {
            "uuid": "ff0b5e52-49c3-4ba3-ba69-aa985054ea6b",
            "value": {
              "value": "001",
              "alias": ""
            },
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "MCC",
            "valueType": "TEXT"
          },
          {
            "uuid": "4q0bqd52-41c3-4vf3-bn69-cc99805e4a6m",
            "value": {
              "value": "1",
              "alias": "Default"
            },
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "RAN Profile",
            "valueType": "ENUM"
          }
        ],
        "state": "feasibilityChecked",
        "supportingResource": [],
        "serviceRelationship": [],
        "supportingService": []
      },
      "appointment": null
    }
  ],
  "orderRelationship": [],
  "relatedParty": [
    {
      "uuid": "136bf8a0-946c-4213-b39a-0a35b3b61eb5",
      "@baseType": "BaseRootEntity",
      "@schemaLocation": null,
      "@type": "io.openslice.tmf.prm669.model.RelatedParty",
      "href": null,
      "name": "admin",
      "role": "REQUESTER",
      "@referredType": "SimpleUsername_Individual",
      "id": "admin",
      "extendedInfo": "admin@osl.org"
    }
  ],
  "state": "ACKNOWLEDGED"
}

Service Order Preview

After submitting a POST request, the work moves to the background. You can track the progress and eventually retrieve your active service details using the Order ID.

To monitor the progress of your order, use the GET method on the specific resource:

  • Method: GET
  • Endpoint: {URL}/tmf-api/serviceOrdering/v4/serviceOrder/{id}
  • Headers: Authorization: Bearer {{access_token}}

Best Practice: Implement a polling mechanism (callback interval) in your external system. Continue querying until the state attribute transitions to "COMPLETED".

...
"orderItem": [
    {
      "uuid": "0745fd3d-5f6a-4118-ad54-fadad111ca47",
      "@baseType": "BaseEntity",
      "@schemaLocation": null,
      "@type": null,
      "href": null,
      "id": "0745fd3d-5f6a-4118-ad54-fadad111ca47",
      "action": "add",
      "orderItemRelationship": [],
      "state": "COMPLETED",
      "service": {
        "uuid": "bc474ff9-d838-42be-9431-a25e1ab78b1b",
        "serviceSpecification": {
          "@baseType": "BaseEntity",
          "@schemaLocation": null,
          "@type": null,
          "href": null,
          "name": "5G Connectivity and Internet Access",
          "version": "0.1.0",
          "targetServiceSchema": null,
          "@referredType": null,
          "id": "dcbc9ed6-bf01-41cc-9c0c-3fe4e2788a77"
        },
        "@baseType": "BaseEntity",
        "@schemaLocation": null,
        "@type": null,
        "href": null,
        "name": "5G Connectivity and Internet Access",
        "id": "bc474ff9-d838-42be-9431-a25e1ab78b1b",
        "category": null,
        "serviceType": null,
        "place": [],
        "relatedParty": [],
        "serviceCharacteristic": [
          {
            "uuid": "bd2c34ff-604a-49e8-adfc-5f4dc8b9f57e",
            "value": {
              "value": "[{\"value\":\"outdoor\",\"alias\":\"Outdoor Radio Units\"}]",
              "alias": null
            },
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "5G Radio Nodes",
            "valueType": "SET"
          },
          {
            "uuid": "d90f4e4e-f924-4421-8363-24f30dfa225b",
            "value": {
              "value": "01",
              "alias": null
            },
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "MNC",
            "valueType": "TEXT"
          },
          {
            "uuid": "5dac7869-8a63-409e-9dad-f331a4f0e3ce",
            "value": {
              "value": "100",
              "alias": null
            },
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "TAC",
            "valueType": "TEXT"
          },
          {
            "uuid": "ff0b5e52-49c3-4ba3-ba69-aa985054ea6b",
            "value": {
              "value": "001",
              "alias": ""
            },
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "MCC",
            "valueType": "TEXT"
          },
          {
            "uuid": "4q0bqd52-41c3-4vf3-bn69-cc99805e4a6m",
            "value": {
              "value": "1",
              "alias": "Default"
            },
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "RAN Profile",
            "valueType": "ENUM"
          }
        ],
        "state": "active",
        "supportingResource": [],
        "serviceRelationship": [],
        "supportingService": [
          {
            "uuid": "7b90b9f3-0793-4bd1-9113-4ffeae67bfd4",
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "5G Connectivity and Internet Access",
            "id": "8f223f7c-0252-453f-bcad-c6e44c6dc6f0",
            "@referredType": "5G Connectivity and Internet Access"
          },
          {
            "uuid": "96815cc1-87b4-4bf9-8191-8b95d927d0e7",
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "open5gs-core_ns@OSM TEN",
            "id": "e95413fc-5ff9-4199-848f-6e60cdf71d53",
            "@referredType": "open5gs-core_ns@OSM TEN"
          },
          {
            "uuid": "98100115-30b7-4fc6-b8a5-32dea123b00b",
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "open5gs-upf_ns@OSM TEN",
            "id": "93bc84d2-392b-4cab-9429-5a285547fa00",
            "@referredType": "open5gs-upf_ns@OSM TEN"
          }
        ]
      },
      "appointment": null
    }
  ],
"state": "COMPLETED"
...

Retrieving Active Service Instances

Once the state is COMPLETED, the fulfillment process has successfully provisioned your resources. You can find the links to your live Services within the order response.

Look for the supportingService array. This contains the references to the actual Service instances running in the environment.

In the example provided, you may find this array at orderItem[0].service.supportingService, since the Service Order contains 1 Order item, hence the [0].

{
    "supportingService": [
        {
            "uuid": "7b90b9f3-0793-4bd1-9113-4ffeae67bfd4",
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "5G Connectivity and Internet Access",
            "id": "8f223f7c-0252-453f-bcad-c6e44c6dc6f0",
            "@referredType": "5G Connectivity and Internet Access"
        },
        {
            "uuid": "96815cc1-87b4-4bf9-8191-8b95d927d0e7",
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "open5gs-core_ns@OSM TEN",
            "id": "e95413fc-5ff9-4199-848f-6e60cdf71d53",
            "@referredType": "open5gs-core_ns@OSM TEN"
        },
        {
            "uuid": "98100115-30b7-4fc6-b8a5-32dea123b00b",
            "@baseType": "BaseEntity",
            "@schemaLocation": null,
            "@type": null,
            "href": null,
            "name": "open5gs-upf_ns@OSM TEN",
            "id": "93bc84d2-392b-4cab-9429-5a285547fa00",
            "@referredType": "open5gs-upf_ns@OSM TEN"
        }
    ]
}

To retrieve the full details of an active Service, use the id found in the supportingService array from the previous step.

  • Method: GET
  • Endpoint: {URL}/tmf-api/serviceInventory/v4/service/{id}
  • Headers: Authorization: Bearer {{access_token}}

Service/Service Order Termination

In a dynamic environment, you may need to modify a running Service/Service Order or decommission it ahead of schedule. Since OpenSlice uses a declarative approach, you manage the Service/Service Order's life by updating its state or timeframe.

The most efficient way to terminate a Service/Service Order and release its resources is to trigger the automatic orchestration logic.

  • Identify: Locate the existing Service Order ID.
  • Update: Issue a PATCH to the Service Order.
  • Trigger: Set the requestedCompletionDate to a past date (e.g., 2010-01-01T00:00:00.000Z).