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.

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.

{
  "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:

{
  "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:

{
  "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.