# Order Management

Create and manage an order to provide, cease or modify a service at a given address.

This follows the concepts in TMF641 - Service Ordering Management API.


## Create an order to provide, cease or modify a service.

 - [POST /service-orders](https://docs.thefibrecafe.net/openapi/prod/supplier-api/gen/order-management/handlecreateorder.md): This endpoint is called to place an order with the supplier to provision a new service
or cease/modify an existing service.

The supplier should validate the order request and accept the order if the validation
is successful or otherwise reject the order. If the order is rejected, a 422 code
should be returned with reason(s) for the rejection in the response.

If the order is accepted, the supplier may return a 202 accepted response without
acknowledging the order if further validation/processing is required. In this scenario,
the supplier must then send an order update (KCI) to later acknowledge the order and
provide the order number.

Alternatively, the supplier can synchronously acknowledge the order by returning a 201
created response with the returned order containing the supplier order number and status
of ACKNOWLEDGED. The order can also be committed at this stage by returning the order
status of IN_PROGRESS.

## Request an amendment to an inflight provide, cease or modify order.

 - [POST /service-order-amendments](https://docs.thefibrecafe.net/openapi/prod/supplier-api/gen/order-management/handleamendorder.md): This endpoint is called to request amendment(s) to an existing inflight order
to provision, modify or cease a service.

A request will contain 1 or more fields to be amended - only fields supplied
should be changed e.g. if a new contact phone number is provided then the existing
contact name and email address would remain the same.

The supplier should validate the amendment request. If the request is invalid or
not possible then a 422 code should be returned with reason(s) for the rejection in
the response.

The supplier may return a 202 accepted response without confirming the cancellation
if further validation/processing is required. In this scenario, the supplier must then
send an order update (KCI) to later confirm the order was cancelled or if rejected.

Alternatively, the supplier can confirm the amendment immediately by returning a
201 created response.

## Request to cancel an inflight provide, cease or modify order.

 - [POST /service-order-cancellations](https://docs.thefibrecafe.net/openapi/prod/supplier-api/gen/order-management/handlecancelorder.md): This endpoint is called to request cancellation of an existing inflight order
to provision/modify/cease a service or for a cancellation other (unsolicited
cease).

The supplier should validate the cancellation request. If the request is invalid or
not possible then a 422 code should be returned with reason(s) for the rejection in
the response.

The supplier may return a 202 accepted response without confirming the cancellation
if further validation/processing is required. In this scenario, the supplier must then
send an order update (KCI) to later confirm the order was cancelled or if rejected.

Alternatively, the supplier can confirm the cancellation immediately by returning a
201 created response.

## Create an order to provide ethernet service.

 - [POST /ethernet/service-orders](https://docs.thefibrecafe.net/openapi/prod/supplier-api/gen/order-management/handlecreateethernetorder.md): This endpoint can be called to place an ethernet order with a supplier to provide service. 
Ability to cease or modify a service will follow in a later update.

The supplier should validate the order request and accept the order if the validation
is successful or otherwise reject the order. If the order is rejected, a 422 code
should be returned with reason(s) for the rejection in the response.

If the order is accepted, the supplier may return a 202 accepted response without
acknowledging the order if further validation/processing is required. In this scenario,
the supplier must then send an order update (KCI) to later acknowledge the order and
provide the order number.

Alternatively, the supplier can synchronously acknowledge the order by returning a 201
created response with the returned order containing the supplier order number and status
of ACKNOWLEDGED. The order can also be committed at this stage by returning the order
status of IN_PROGRESS.