Clarification needed for exchangeOffer price and refundableAmount fields

[dhoeweling-sqills]

We need clarification on the exchangePrice and refundableAmount fields in the ExchangeOffer object. Our current assumptions are:

• exchangePrice: The sum of all prices of the bookingParts in the offer.
• refundableAmount: The actual balance between exchanged bookingParts and new bookingParts, including the fee.
  Calculated as: sum(exchangedBookingParts.price) - sum(newBookingParts.price) - exchangeFee
  • If positive: The customer gets a refund.
  • If negative: The customer has to pay the difference.

Questions

1. Are our assumptions about exchangePrice and refundableAmount correct?
2. What is the exact purpose of each field?
3. How should these fields be used in different scenarios?

Examples

To illustrate our understanding, here are two examples:

Example 1

• Price for new bookingParts: 100 EUR
• Price for exchanged bookingParts: 50 EUR
• Exchange fee: 10 EUR

{
  "exchangeFee": {
    "amount": 1000,
    "currency": "EUR",
    "scale": 2
  },
  "exchangePrice": {
    "amount": 10000,
    "currency": "EUR",
    "scale": 2
  },
  "refundableAmount": {
    "amount": -6000,
    "currency": "EUR",
    "scale": 2
  }
}

Example 2

• Price for new bookingParts: 100EUR
• Price for exchanged bookingParts: 150EUR
• Exchange fee: 10EUR

{
  "exchangeFee": {
    "amount": 1000,
    "currency": "EUR",
    "scale": 2
  },
  "exchangePrice": {
    "amount": 10000,
    "currency": "EUR",
    "scale": 2
  },
  "refundableAmount": {
    "amount": 4000,
    "currency": "EUR",
    "scale": 2
  }
}

[pgitips]

We made different assumptions in our implementation of exchange flow.
We calculate the same sum(exchangedBookingParts.price) - sum(newBookingParts.price) - exchangeFee.

• if negative, balance in favor of the purchaser:
  exchangePrice: null amount
  refundableAmount: The balance as a positive amount

• if positive, balance in favor of the retailer:
  exchangePrice: The balance as a positive amount
  refundableAmount: null amount

The exchangeFee has a clear meaning and is always positive or null.
Each field is always positive.
The prices of all booking parts in the offer can still be calculated by adding all bookingParts price.
We're also interested in a clarification on meanings of this field.

[Linus-Turnit]

Me and Tim suggest this.

• exchangePrice – The price of all booking parts in the exchangeOffer (including all exchangeFees)
• exchangeFee – Sum of exchangeFees
• refundableAmount – When exchanging to something cheaper. This is the amount to pay back to the customer (credit amount)
• amountToBePaid (new field) – If the user must pay more to do the exchange. This is the amount. (debit amount)

The naming of the new field must be handled by the group. Is customerCost an alternative?

[schlpbch]

Next Step

• Alignment between @pgitips and @Linus-Turnit and @dhoeweling-sqills whether we have shared view.

[dhoeweling-sqills]

I think we can work with this proposal. I just would like it very clearly documented that refundableAmount and amountToBePaid are mutually exclusive, e.g. if the customer is owed money because the exchange is cheaper refundableAmount will be filled with the corresponding value and therefore amountToBePaid must either be empty or 0.

Applied to the examples from above:

Example 1

• Price for new bookingParts: 100 EUR
• Price for exchanged bookingParts: 50 EUR
• Exchange fee: 10 EUR

{
  "exchangeFee": {
    "amount": 1000,
    "currency": "EUR",
    "scale": 2
  },
  "exchangePrice": {
    "amount": 11000,  
    "currency": "EUR",
    "scale": 2
  },
  "refundableAmount": {
    "amount": 0,
    "currency": "EUR",
    "scale": 2
  },
  "amountToBePaid": {
    "amount": 6000,
    "currency": "EUR",
    "scale": 2
  }
}

Example 2

• Price for new bookingParts: 100EUR
• Price for exchanged bookingParts: 150EUR
• Exchange fee: 10EUR

{
  "exchangeFee": {
    "amount": 1000,
    "currency": "EUR",
    "scale": 2
  },
  "exchangePrice": {
    "amount": 11000,
    "currency": "EUR",
    "scale": 2
  },
  "refundableAmount": {
    "amount": 4000,
    "currency": "EUR",
    "scale": 2
  },
  "amountToBePaid": {
    "amount": 0,
    "currency": "EUR",
    "scale": 2
  }
}

[Azurab]

PKP has implemented the same approach as @pgitips described above: ExchangeOffer must have exchangePrice (if positive or neutral balance) or refundableAmount (if negative balance), never both.
BTW. amounts are always non-negatives (even for refundableAmount).