Order / Cart **

The order capability allows resellers to group bookings together under an Order object. Through the Order capability API interface (implemented along side the OBS interface), Order holds can be extended, confirmed, or cancelled, performing the same operation on each booking contained within the Order.

X-Capabilities: redeam/cart

Additional information on Order-specific endpoints (Fetch, Extend, Confirm, Cancel) can be found in the Operator API v2 Capabilities APIAPI reference.

Adding a Booking to an Order

New bookings can be associated with an existing Order by providing a unique orderId in the Create Booking request. If no Order exists under the given orderId, a new Order is created. New Orders always start in the ON_HOLD status.

If an order is not cancelled or confirmed before the utcExpiresAt time, the order will transition into an EXPIRED status and no longer be usable.

Order Operations

Every Order operation (Extend, Confirm, Reject, or Cancel) acts collectively on all bookings within the Order. These collective operations are to be executed all-or-nothing; that is, if any one booking operation fails, the entire Order operation should fail. This may occur because bookings placed earlier in the order have expired before receiving confirmation, or because an individual booking in the Order was confirmed or cancelled before the Order operation was committed. In either event, the requested operation must fail - any changes to the Order or its Booking objects should be reverted or discarded, and the client must receive an appropriate error.

Extending an Order

An Order may have its hold period extended via the /extend endpoint via POST request. The client must provide a reason for the extension, along with a requested amount of time (in minutes) the client wishes to extend the hold by.

The OBS may accept the extension request and extend the hold by the requested duration, or any arbitrary duration. If the extension is rejected, an error must be returned to the client.

Confirming an Order

An Order may be confirmed through the Order confirmation endpoint via a POST request along with the customer's contact information.

The OBS may accept and confirm the Order, along with all bookings the Order contains, if all objects are in the ON_HOLD state. If any object is not in the ON_HOLD state, or if any object has a utcHoldExpiration time in the past, the confirmation request may be REJECTED.

Cancelling an Order

An Order and all associated bookings can be cancelled via the Order DELETE method. The client must provide a reason for the cancellation in the request body.

A successful cancellation request on an Order in the ON_HOLD status should expire the hold. If the Order has already been confirmed, the OBS may accept or reject the cancellation request.