---
sidebar_label: 'Reserving a deal'
sidebar_position: 2
---

# Reserving a deal

## Process to reserve a deal for an order
When building a loyalty integration, the loyalty system can be involved in applying discounts to orders for all tenants, regardless of whether the order is created by a registered or temporary user. A deal is always scoped to an order, and by creating a deal and adding discounts to that deal, the discounts are automatically applied to the order.

The process to create and reserve a deal for _all_ orders is described below.

```mermaid
sequenceDiagram
    actor user as User
    participant fo as Future Ordering
    participant loyint as Loyalty Integration 

    note over fo: Future Ordering is configured to request <br />the loyalty system to register deals/discounts for all orders

    user ->> fo: Start order process
    note over fo: Order created
    fo->>loyint: (Event) reservation_required
    loyint-->>fo: 202 Accepted
    loyint->>loyint: Process event
    loyint->>fo: Create deal
    fo-->>loyint: deal-id
    loyint->>fo: Reserve deal for deal-id
    note over user, loyint: User does not need to wait for this process to complete,<br />user can keep adding items while this is handled in the background
```

:::note
 Future Ordering must add configuration to enable the loyalty integration. When configuration is added the reservation required event will be published for the loyalty integration. 
 :::

When a user first initiates an order, all configured loyalty systems must reserve at least one deal for that order. The Future Ordering backend checks which external loyalty systems exist for an order, and a `reservation_required` event is sent for each one. Each external loyalty system is represented by a `key` that is sent in the event. Future Ordering sets and provides the `key` when needed.

## Reservation required event
Example of a reservation required event.

```json
{
  "specversion": "1.0",
  "data": {
    "tenantId": "my_tenant",
    "key": "key-for-my-own-integration",
    "orderVersionId": "1",
    "orderId": "ebuvUDP0i8i"
  },
  "dataContentType": "application/json",
  "id": "7fd89d0b-76bd-42b8-bce3-1c149bddfa92",
  "source": "https://api.futureordering.com",
  "time": "2024-05-21T10:30:54.990511+00:00",
  "type": "com.futureordering.order.deal.reservation_required"
}
```

- `tenantId` - Future Ordering tenant ID. This is mainly needed if an integration is built for several tenants.
- `key` - key of the responsible loyalty integration.
- `orderVersionId` - for which order version this event is valid for
- `orderId` - for which order this event is valid for

When `reservation_required` is received by the Loyalty Integration, it is expected to create a deal and then reserve it. Deals are always scoped to an order and exist under the orders domain.

## Create and reserve deal APIs
Example to create a deal for an order.

- POST `/orders/{order-id}/deals`

Example request:

```json
{
  "visibility": "notShown", 
  "orderVersionId": "1",
  "title": { 
    "translations": {
      "default": "default translation", 
      "en-Gb": "British English translation"
    }
  }, 
  "description": { 
    "translations": {
      "default": "default translation",
      "en-Gb": "British English translation"
    }
  },
  "name": "my delicious deal", 
  "key": "key-for-my-own-integration", 
  "discounts": []
}
```

- `visibility` - Possible values are "notShown" and "showAsOwnLine". These affect how the _deal_ is shown in the UI. This property has no effect on the visibility of discounts.
- `orderVersionId` - for which order version this request should be applied for
- `title` - Title of the deal shown in UI when `visibility = showAsOwnLine`. The default value in the translation object is mandatory.
- `description` - Description of the deal that may be visible in UI when `visibility = showAsOwnLine`.
- `key` - to identify which loyalty integration that is responsible for this deal. Must be the same as in the initial event above.
- `name` - Internal name that is not shown in UI.
- `orderId` - for which order this event is valid for
- `discounts` - Discounts valid for this version of the order. It is possible to add discounts in the create-deal request, but this is not common.

Response code is 201 with a location header:

https://api.futureordering.com/orders/ebuvUDP0i8i/deals/a0e34dd7-1052-4918-9896-2930d4c121e1

Example response body:

```json
{
  "statusCode": "successful",
  "dealId": "a0e34dd7-1052-4918-9896-2930d4c121e1",
  "message": "Deal Created!",
  "innerCode": "a0e34dd7-1052-4918-9896-2930d4c121e1",
  "successful": true,
  "outerCode": 200
}
```

Once a deal is created, it is expected to be reserved for activation and application to the order. This is done by calling the reserve action without a body (use the location header and add `/reserve`):

- POST `/orders/{order-id}/deals/{deal-id}/reserve`

The response code is `204 No Content`.