Order Endpoints

Endpoints used for managing orders and reservations are described here.

Currently, the latest functions are offered under the v4/order controller.

We recommend a migration plan to those partners that are integrated to our platform with v3/order .

---

The order flow is shown here.

Reservations

• A reservation is valid for a predetermined period of time. For the time being, a reservation is valid for 15 minutes with a possibility of 2 extensions, again for 15 minutes each. Extensions are made by v4/order/extend.
  • Multiple layers of flexibility is to be introduced to reservation validity periods as future work.
• A reservation that is not completed before it expires is automatically canceled.
• A valid reservation could be canceled explicitly at any given time by v4/order/cancel endpoint.
• A valid reservation could be completed and turned into an order at any given time by v4/order/complete endpoint. Once a reservation is completed, it creates the order for the reservation.

Orders

• A completed order is an optional predecessor state of a fulfilled order. It is not relevant when immediate fulfilment is chosen while creating the order. A completed order keeps the digital asset encrypted and would not expose it until the order is explicitly fulfilled by v4/order/fulfil endpoint.

---

Endpoints

1. Create an order or reservation
2. Retrieve an order or reservation
3. Extend a reservation
4. Complete a reservation
5. Fulfil an order
6. Cancel an order or reservation

---

1. Create an order or reservation

Order life cycle starts with the order being created.

Reservations and orders are both created with this endpoint. orderType argument defines if a request is to be handled as a reservation or an order.

After a reservation is completed or an order is created without a reservation by using the orderType argument, the life cycle of an order starts.

2. Retrieve an order or reservation

Returns the specified order or reservation.

An order or reservation can be identified in 2 different ways. This endpoint either expects the orderGuid that VaultN uses to identify orders or clientOrderReference that vaults can attach to their create order requests. clientOrderReference represents the third party internal identifier that actors could use to operate the API with their own internal identifiers. If provided, it relates to orderGuid directly.

3. Extend a reservation

When a reservation is created, it has a certain time before it expires and is canceled on its own. In case, the time frame is not enough, a reservation then can be extended, twice at most. This endpoint requires orderGuid as an argument to determine which reservation is to be extended.

4. Complete a reservation

A valid reservation could be completed by using this endpoint. Just like extending, this endpoint requires a single parameter (orderGuid) to specify which reservation is to be completed. A completed reservation evolves into a created order. This step usually follows after the payment is secured by retailers.

5. Fulfil an order

When immediate fulfilment is not chosen, a completed order has to be fulfilled explicitly to decrypt the asset and extract it out of VaultN, thus ending its active life cycle (with the exception of canceled orders and return requests which are subjected to business arrangements in between vaults.).

The order to be fulfilled is specified by orderGuid in the request.

6. Cancel an order or reservation

At any point in a reservation's or order's life cycle, it could be canceled. Cancelation has slightly different implications based on the circumstances of the request. The specific reservation or order is specified by orderGuid in the request.

• If a reservation is canceled at any given time in its life cycle, then it never becomes an order and is just dropped.
• If an order that is yet to be fulfilled is canceled, then it is automatically refunded since the asset is still not exposed.
• In a fulfilled order is canceled, what happens next is then defined by the business agreements in place in between vaults.