# Order Management
Order Management supports the full lifecycle of service orders, including creation, modification, amendment, and cancellation.
# Quick Start Workflow
- Check Service Availability:
- Use the Service Availability API to determine available services and site information.
- Book Appointment (if needed):
- Use the Appointment Management API to reserve a slot if installation is required.
- Place Order:
- Use the correct
orderType(see below) and include all required fields.
- Use the correct
- Amend, Modify, or Cancel:
- Use the appropriate endpoints to update or cancel orders as needed.
# Service Orders Endpoint (Provide)
# POST /WholesaleGateway/v1.0/gateway/service-orders (Provide)
# Description:
Create a new service order (Provide).
# Headers:
X-Request-ID: string (required)X-Conversation-ID: string (required)Tenant: string (required)Authorization: string (required) - Bearer token for authentication
# Request Body:
{
"id": 127,
"orderType": "NEW",
"tenant": "NETOMNIATEST",
"address": { "id": "10025559646", "type": "UPRN" },
"serviceOrderItem": {
"serviceSpecification": { "id": "fttp" },
"serviceCharacteristics": [
{ "name": "LINE_PROFILE", "value": "55/55" },
{ "name": "AUTHENTICATION_AGENT", "value": "DHCPRelayAgent" },
{ "name": "REMOTE_ID", "value": "remote123" },
{ "name": "RETAILER_ID", "value": "retailer456" },
{ "name": "MINIMUM_SPEED", "value": "100" },
{ "name": "END_USER_TYPE", "value": "RESIDENTIAL" },
{ "name": "CONTRACT_TERM", "value": "12" },
{ "name": "ECC_CHARGEBAND", "value": "A" },
{ "name": "TRC_CHARGEBAND", "value": "1" },
{ "name": "CARE_LEVEL", "value": "STANDARD" },
{ "name": "STATIC_IP_REQUESTED", "value": "false" }
]
},
"primaryContact": { "name": "Ciaran Test", "email": "ciaran@test.com", "phoneNumber": "01234 567890" },
"secondaryContact": { "name": "Tommy Thompson", "phoneNumber": "09876 543214" },
"appointmentReservationId": 163,
"appointmentReservationReference": "75f4877f-9bd8-4e94-b627-83136db877df9",
"requestedCompletionDate": "2025-07-28",
"engineerTasks": ["INSTALL_ROUTER", "TEST_SINGLE_DEVICE"],
"hazards": "Hazardous materials stored on site",
"onSiteRestrictions": "Restricted access",
"notes": "Lorem ipsum dolor sit amet..."
}
# Response:
Status Code: 202 Accepted
The order has been accepted for processing. No response body is returned.
Note: Order acknowledgment and status updates will be sent via KCI (Keep Customer Informed) events. Monitor your webhook endpoint for order status notifications.
# Service Orders Endpoint (Cease)
# POST /WholesaleGateway/v1.0/gateway/service-orders (Cease)
# Description:
Cease an existing service order.
# Headers:
X-Request-ID: string (required)X-Conversation-ID: string (required)Tenant: string (required)Authorization: string (required) - Bearer token for authentication
# Request Body:
{
"id": 203,
"orderType": "CEASE",
"tenant": "NETOMNIATEST",
"serviceId": "f41b356c-11d2-4d65-b8b3-258461af9c2c",
"requestedCompletionDate": "2025-05-20T09:00:00.000Z"
}
# Response:
Status Code: 202 Accepted
The order has been accepted for processing. No response body is returned.
Note: Order acknowledgment and status updates will be sent via KCI (Keep Customer Informed) events. Monitor your webhook endpoint for order status notifications.
# Service Orders Endpoint (Modify)
# POST /WholesaleGateway/v1.0/gateway/service-orders (Modify)
# Description:
Modify an existing service order.
# Headers:
X-Request-ID: string (required)X-Conversation-ID: string (required)Tenant: string (required)Authorization: string (required) - Bearer token for authentication
# Request Body:
{
"id": 3002,
"orderType": "MODIFY",
"tenant": "NETOMNIATEST",
"serviceId": "24bc2115-d829-47fb-802a-ceef790bf999",
"serviceCharacteristics": [
{ "name": "LINE_PROFILE", "value": "80/20" },
{ "name": "MINIMUM_SPEED", "value": "200" }
],
"requestedCompletionDate": "2025-04-10T09:00:00.000Z"
}
# Response:
Status Code: 202 Accepted
The order amendment has been accepted for processing. No response body is returned.
Note: Order acknowledgment and status updates will be sent via KCI (Keep Customer Informed) events. Monitor your webhook endpoint for order status notifications.
# Service Order Amendments Endpoint (Provide)
# POST /WholesaleGateway/v1.0/gateway/service-order-amendments (Provide)
# Description:
Amend a service order (Provide).
# Headers:
X-Request-ID: string (required)X-Conversation-ID: string (required)Tenant: string (required)Authorization: string (required) - Bearer token for authentication
# Request Body:
{
"id": 1001,
"orderId": 126,
"serviceCharacteristics": [
{ "name": "LINE_PROFILE", "value": "100/100" },
{ "name": "MINIMUM_SPEED", "value": "500" }
],
"primaryContact": { "name": "Billy Brown", "email": "billy@brown.com", "phoneNumber": "01234 567890" },
"secondaryContact": { "name": "Barbara Brown", "email": "barbara@brown.com", "phoneNumber": "01234 567890" },
"appointmentReservationId": 162,
"appointmentReservationReference": "2dcfb519-441e-4855-82e3-75cd7b663091",
"requestedCompletionDate": "2025-07-20",
"engineerTasks": ["TEST_SINGLE_DEVICE", "INSTALL_BBU"],
"hazards": "VERY HAZARDOUS",
"onSiteRestrictions": "very restricted",
"notes": "Hello this is my note"
}
# Response:
Status Code: 202 Accepted
The order amendment has been accepted for processing. No response body is returned.
Note: Order acknowledgment and status updates will be sent via KCI (Keep Customer Informed) events. Monitor your webhook endpoint for order status notifications.
# Service Order Amendments (Cease)
# POST /WholesaleGateway/v1.0/gateway/service-order-amendments (Cease)
# Description:
Amend a service order (Cease).
# Headers:
X-Request-ID: string (required)X-Conversation-ID: string (required)Tenant: string (required)Authorization: string (required) - Bearer token for authentication
# Request Body:
{
"id": 234,
"orderId": 2005,
"requestedCompletionDate": "2025-02-11T09:00:00.000Z"
}
# Response:
Status Code: 202 Accepted
The order amendment has been accepted for processing. No response body is returned.
Note: Order acknowledgment and status updates will be sent via KCI (Keep Customer Informed) events. Monitor your webhook endpoint for order status notifications.
# Service Order Amendments (Modify)
# POST /WholesaleGateway/v1.0/gateway/service-order-amendments (Modify)
# Description:
Amend a service order (Modify).
# Headers:
X-Request-ID: string (required)X-Conversation-ID: string (required)Tenant: string (required)Authorization: string (required) - Bearer token for authentication
# Request Body:
{
"id": 234,
"orderId": 9800156,
"requestedCompletionDate": "2025-02-12T09:00:00.000Z"
}
# Response:
Status Code: 202 Accepted
The order amendment has been accepted for processing. No response body is returned.
Note: Order acknowledgment and status updates will be sent via KCI (Keep Customer Informed) events. Monitor your webhook endpoint for order status notifications.
# Service Order Cancellations
# POST /WholesaleGateway/v1.0/gateway/service-order-cancellations
# Description:
Cancel a service order.
# Headers:
X-Request-ID: string (required)X-Conversation-ID: string (required)Tenant: string (required)Authorization: string (required) - Bearer token for authentication
# Request Body:
{
"id": 345,
"orderId": 10000000004,
"reasonCode": "CUSTOMER_CHANGED_MIND"
}
# Response:
Status Code: 202 Accepted
The order cancellation has been accepted for processing. No response body is returned.
Note: Order acknowledgment and status updates will be sent via KCI (Keep Customer Informed) events. Monitor your webhook endpoint for order status notifications.
# Enum Values
# orderType
- Provide:
NEW: New service install (use when no active service exists at the address)START: Restart unused line/ONT (use when infrastructure exists but service is inactive)TAKEOVER: Takeover active service (WLTO; use for intra-Supplier transfers or when a service is being moved between customers)TRANSFER: Transfer service to new providerSWAP: Product family migration/regrade
- Cease:
CEASE: Cease existing service (requiresserviceId)
- Modify:
MODIFY: Modify existing service (requiresserviceId)
# Order Type Decision Table
| Scenario | Site Information | Existing Service | Intended Action | orderType |
|---|---|---|---|---|
| New install at address | newLine: true | No | Provide new service | NEW |
| Restart unused ONT/line | existingLines present | No (inactive) | Start service | START |
| Takeover (intra-Supplier transfer) | existingLines present | Yes (active) | Move between customers | TAKEOVER |
| Transfer to new provider | existingLines present | Yes (active) | Change provider | TRANSFER |
| Product migration/regrade | Any | Yes (active) | Change product | SWAP |
| Cease service | Any | Yes (active) | Stop service | CEASE |
| Modify service | Any | Yes (active) | Change config/details | MODIFY |
# engineerTasks
INSTALL_ROUTERTEST_SINGLE_DEVICEADDITIONAL_CABLINGTEST_MULTIPLE_DEVICESINSTALL_BBUVOICE_REINJECTIONPROVE_IP_VOICE
# reasonCode (Order Cancellation)
CUSTOMER_CHANGED_MINDINSTALL_FAILEDNETWORK_ISSUENO_LONGER_REQUIREDOTHERNO_AUTHORISATIONCUSTOMER_NOT_AWAREDELIBERATE_MISLEADPURCHASED_DIFFERENT_PRODUCTEND_USER_NOT_MOVING
# Field Descriptions
{
"id": 1,
"orderType": "NEW",
"tenant": "string",
"address": {
"id": "10025559646",
"type": "UPRN"
},
"serviceOrderItem": {
"serviceSpecification": {
"id": "fttp",
"name": "FTTP"
},
"serviceCharacteristics": [
{
"name": "LINE_PROFILE",
"value": "55/55"
}
]
},
"primaryContact": {
"name": "string",
"email": "bobjones@gmail.com",
"phoneNumber": "string"
},
"secondaryContact": {
"name": "string",
"email": "bobjones@gmail.com",
"phoneNumber": "string"
},
"appointmentReservationId": 1,
"appointmentReservationReference": "string",
"requestedCompletionDate": "2025-01-18",
"engineerTasks": [
"INSTALL_ROUTER"
],
"hazards": "string",
"onSiteRestrictions": "string",
"notes": "string"
}
| Field | Type | Required | Description |
|---|---|---|---|
| id | integer | Yes | Unique identifier for the order or request |
| orderType | string | Yes | Type of order (see enum above) |
| tenant | string | Yes | Tenant placing the order |
| address | object | Yes | Address identifier { id: string, type: string } |
| serviceOrderItem | object | Yes (Provide) | Service order item (see below) |
| └─ serviceSpecification | object | Yes | { id: string, name?: string } |
| └─ serviceCharacteristics | array | Yes | Array of { name: string, value: string } for provide orders |
| primaryContact/secondaryContact | object | No | { name: string, email?: string, phoneNumber: string } |
| appointmentReservationId/Reference | integer/string | No | Appointment identifiers |
| requestedCompletionDate | string | No | Requested date for completion (ISO 8601) |
| engineerTasks | array | No | Array of engineer tasks (see enum above) |
| hazards/onSiteRestrictions/notes | string | No | Additional info |
| serviceCharacteristics | array | Yes (Modify) | Array of { name: string, value: string } for modify orders |
| serviceId | string | Yes (Cease/Modify) | Unique identifier for the service |
| orderId | integer | Yes (Amend/Cancel) | Unique id identifying the service order |
| reasonCode | string | Yes (Cancel) | Reason for cancellation (see enum above) |
# Service Characteristics (name/value pairs)
| Name | Description | Example Values |
|---|---|---|
| LINE_PROFILE | Line profile specification | "55/55", "80/20", "100/100" |
| AUTHENTICATION_AGENT | Authentication method | "DHCPRelayAgent" |
| REMOTE_ID | Remote identifier | "remote123" |
| RETAILER_ID | Retailer identifier | "retailer456" |
| MINIMUM_SPEED | Minimum guaranteed speed | "100", "200", "500" |
| END_USER_TYPE | Type of end user | "RESIDENTIAL", "BUSINESS" |
| CONTRACT_TERM | Contract term in months | "12", "24" |
| ECC_CHARGEBAND | ECC charge band | "A", "B", "C" |
| TRC_CHARGEBAND | TRC charge band | "1", "2", "3" |
| CARE_LEVEL | Service care level | "STANDARD", "PREMIUM" |
| STATIC_IP_REQUESTED | Whether static IP is requested | "true", "false" |
| DN_PORT_NUMBER | DN port number | "1", "2" |
| DN_PORT_DATETIME | DN port datetime | "2025-01-18T08:00:00.000Z" |
| LINE_ID | Line identifier | "LINE-001" |
| SERVICE_ID | Service identifier | "SERVICE-001" |
| ENNI_ID | ENNI identifier | "ENNI-001" |
| SERVICE_VLAN_ID | Service VLAN ID | "100" |
| CUSTOMER_VLAN_ID | Customer VLAN ID | "200" |
| CABLE_LINK_ID | Cable link identifier | "CABLE-001" |
| CIRCUIT_REFERENCE | Circuit reference | "CIRCUIT-001" |
| SITE_NAME | Site name | "Site A" |
| SITE_LOCATION | Site location | "Location B" |
| ONT_FLOOR | ONT floor location | "Ground" |
| ONT_MANUFACTURER | ONT manufacturer | "Huawei" |
| ONT_PORT | ONT port | "1" |
| ONT_POSITION | ONT position | "Rack A" |
| ONT_REFERENCE | ONT reference | "ONT-123" |
| ONT_ROOM | ONT room location | "Communications Room" |
| ONT_SERIAL_NUMBER | ONT serial number | "SN123456789" |
| COMPANY_NAME | Company name | "Company Ltd" |
| PROJECT_REFERENCE | Project reference | "PROJECT-001" |
| SITE_VISIT_REASON | Reason for site visit | "Installation" |
# Error Handling
| HTTP Status | Error Code | Description | When it Occurs |
|---|---|---|---|
| 400 | MALFORMED_REQUEST | The request could not be understood by the server due to malformed syntax | Invalid or missing parameters, malformed JSON |
| 401 | NOT_AUTHORISED | The request was not authorised | Missing or invalid OAuth token |
| 422 | INVALID_REQUEST | The request did not satisfy validation | Invalid orderType, missing required fields |
| 500 | SUPPLIER_FAULT | An internal error occurred | Unexpected server error |
| 504 | SUPPLIER_TIMED_OUT | The Netomnia API timed out | Request timeout |
# Example Error Response
{
"uuid": "d9bb42fa-a6c4-4537-8e05-e8387638cf31",
"code": "INVALID_REQUEST",
"messages": ["Information about validation here..."]
}
# Retrieving Service Identifiers
For cease or modify orders, you must provide a valid serviceId. Retrieve this by using the Service Availability API to check for active/ceased services at the address.