Flex allows lots of flexibility for your providers in terms of how they can set their pricing. This guide walks you through how price is defined in Flex.
Table of Contents
NOTE! The current default pricing method has deprecated our old custom pricing feature. If you are looking for the old custom pricing background article, it can be found here.
It's common for a marketplace to base it's pricing on the length of a booking, on a number of booked units, or the combination of these two. With Flex you can design your pricing using these two parameters but the pricing can also be extended to support more complicated business models or even be replaced with a completely different model altogether. Here are some examples of common pricing schemes you might want to add on top of the regular listing price.
- Add-ons. Upsell additions on top of the regular price. Examples: cleaning fee, insurance, delivery.
- Discount based on booking length. An example: daily price is $20, weekly price $70, and monthly price $200. Another example: 20% discount on daily rate for bookings of 5 or more days, 30% discount on bookings of 10 or more days, and so on.
- Taxes. Add any type of tax rate to the listing price and display them as separate line items in the receipt.
- Offer multiple pricing packages in the same listing. An example: a hairdresser offers both haircuts and hair dying.
- Seasonal pricing. Examples: weekends cost more than weekdays, summers cost more than winters, and so on.
- Quantity discount. An example: booking a room for two people costs $100, and after that, each additional person costs $20 extra.
All of these options can be achieved with the Flex pricing functionality. In this article, we'll look a bit closer at how pricing works in Flex and how pricing schemes can be designed.
- Line item: Something that affects transaction price, for example, a booking for two nights, a cleaning fee, or a customer commission. Think of as a line in a receipt.
- Line total: Total price of a line item.
- Payin total: Amount of money that a customer pays for a transaction. The value is the sum of line items that apply to the customer.
- Payout total: Amount of money a provider receives from a transaction. The value is the sum of line items that apply to the provider.
In Flex, the total price of a transaction is defined by its line items. Line items describe what is included in a transaction. It can be a varying set of things from the number of booked units to customer and provider commissions, add-ons, discounts, or payment refunds.
A transaction gets its price from the
action . The action takes a list of line items as a parameter. Remember,
privileged-set-line-items action needs to be placed in
a privileged transition.
Every line item has a unit price and one of the following attributes: quantity or percentage. The quantity attribute can be used to denote the number of booked units, like the number of booked nights. Quantity can also be defined as a multiplication of units and seats. The percentage param is used when modeling commissions for example. Based on these attributes a line total is calculated for each line item. Line totals then define the total payin and payout sums of the transaction.
The following arguments can be passed in a line item to the Flex API:
code: A string that identifies the line item. Must start with
line-item/, for example,
unitPrice: Price of a single unit of the line item, mandatory.
lineTotal: Total value of the line item, can be negative.
quantity: Total amount of units. Can be defined explicitly or calculated by multiplying
percentage: A percentage that is used to calculate the line total.
seats: Number of seats that are used to calculate the quantity.
units: Number of units. In combination with seats, forms quantity.
includeFor: An array containing strings
provider. Defines which party of a transaction the line item applies to.
lineTotal is not a mandatory parameter. Flex will calculate the
line total and if one is provided, it will validate the
parameter against the calculated value.
The price of a line item can be calculated in three ways, combining the
unitPrice with either
percentage. The following tables provide examples of all price
Use unit price and quantity to calculate the price when you want to multiply a fixed fee with a quantity.
|"line-item/nights"||new Money(5000, "USD")||3||new Money(15000, "USD")||["customer", "provider"]|
|"line-item/cleaning-fee"||new Money(7500, "USD")||1||new Money(7500, "USD")||["customer", "provider"]|
|"line-item/fixed-customer-commission"||new Money(2500, "USD")||1||new Money(2500, "USD")||["customer"]|
lineTotal is calculated as
unitPrice * quantity.
Use unit price combined with seats and units when the number of participants affects the price.
|"line-item/nights"||new Money(5000, "USD")||3||2||new Money(30000, "USD")||["customer", "provider"]|
lineTotal is calculated as
unitPrice * seats * units.
Use unit price and percentage when the line total is calculated as a percentage of some other (sub)total.
|"line-item/coupon-discount"||new Money(50000, "USD")||-15||new Money(-7500, "USD")||["customer", "provider"]|
|"line-item/customer-commission"||new Money(50000, "USD")||15||new Money(7500, "USD")||["customer"]|
|"line-item/provider-commission"||new Money(50000, "USD")||-15||new Money(-7500, "USD")||["provider"]|
lineTotal is calculated as
unitPrice * percentage / 100.
Refunds are created with the
action. It sets transaction pay in and pay out amounts to zero and
creates reverse line items that undo all the previous line items. Note,
calculate-full-refund action can be run only once during a
The action calculates a full refund. Partial refunds are not supported by Flex at the moment.