---
sidebar_label: 'Post-order deal handling'
sidebar_position: 4
---

# Post-order deal handling

## Process to handle a deal after order placement/failures

The sequence diagram below illustrates the flow after order placement. The first part of the diagram is the same as in the fulfillment flow.

```mermaid
sequenceDiagram
    actor user as User
    participant fo as Future Ordering
    participant loyint as Loyalty Integration 
    participant loy as Loyalty 
    participant posint as POS
    
    user ->> fo: Add item/remove item/change order
    fo ->> loyint: (Event) order.deal.fulfillment_required
    loyint->>fo: Get order with order-id
    loyint ->> loy: Are there discounts for this order? 
    loy-->>loyint: Discounts
    loyint ->> fo: Updated discount information with POS Discount IDs
    fo ->> user: Display provided discounts

    user ->> fo: Pay and Place order
    fo ->> posint: Place Order, including<br/>mapping and discount information
    note over posint: Places order
    note over fo, loy: Handling deal flow after order placement
    alt Order placement successful
        posint ->> fo: Order is placed, checknumber: 1234
        fo ->> user: Order placed, 1234
        fo ->> loyint: (Event) order.deal.capture_requested
        note over loyint: Register points on user
        loyint->>fo: Get deal for deal-id or get deals for order-id
        fo-->>loyint:  
        loyint->>loy: Mark order/deals as captured/purchased
        loyint->>fo: Capture deal for deal-id or all deals for this order
    else Order placement failed
        fo ->> user: Order placement failed
        fo ->> loyint: (Event) order.deal.annulment_requested
        note over loyint, loy: Depends on how loyalty system functions  <br /> is this handled per order or per deal
        loyint->>fo: Get deal for deal-id or get deals for order-id
        loyint->>loy: Mark order/deals as annul/void purchase
        loyint->>fo: Annul deal for deal-id or all deals for order
        note over loyint: Annul deals in the Loyalty system if a promotion code, gift, or similar is connected to the order
    end
```

## Capture requested event

```json
{
  "specversion": "1.0",
  "data": {
    "tenantId": "my_tenant",
    "key": "key-for-my-own-integration",
    "orderVersionId": "10",
    "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.capture_requested"
}
```

When this event is received by the Loyalty Integration, it indicates that the order placement is successful. The deal/order should then be marked as captured in the external Loyalty system to register points for the user and mark any discount codes/deals as used. Once this is done in the Loyalty system, all deals for the order should be marked as captured in Future Ordering. This can be done by using the `/capture` action endpoint or one of the PATCH endpoints.

- POST `/orders/{order-id}/deals/{deal-id}/capture`
  - No request body needed. Response code `204 No Content`
- PATCH `/orders/{order-id}/deals`

PATCH request for `isCaptured`:

```json
{
  "a0e34dd7-1052-4918-9896-2930d4c121e1": {
    "isCaptured": true
  }
}
```

Response for PATCH request:

```json
{
  "statusCode": "successful",
  "message": "Patched",
  "innerCode": null,
  "successful": true,
  "outerCode": 200
}
```

## Annulment requested event

```json
{
  "specversion": "1.0",
  "data": {
    "tenantId": "my_tenant",
    "key": "key-for-my-own-integration",
    "orderVersionId": "10",
    "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.annulment_requested"
}
```

When this event is received by the Loyalty Integration, it indicates that the order placement has failed or encountered a similar issue. In such cases, the deal/order should be marked as annulled in the external Loyalty system to void any discount codes/deals. This can be done by using the action endpoint `/annul` or one of the PATCH endpoints.

- POST `/orders/{order-id}/deals/{deal-id}/annul`
  - No request body needed. Response code `204 No Content`
- PATCH `/orders/{order-id}/deals`

PATCH request for `isAnnulled`:

```json
{
  "a0e34dd7-1052-4918-9896-2930d4c121e1": {
    "isAnnulled": true
  }
}
```

Response for PATCH request:

```json
{
  "statusCode": "successful",
  "message": "Patched",
  "innerCode": null,
  "successful": true,
  "outerCode": 200
}
```