Component: PRICING
Abstract
This component allows setting and retrieving prices for experience product components, such as pricing categories, pickups, extras and so on.
Values for this component are provisioned via ExperienceComponentsDto.pricing which is of ExperiencePricingDto type.
Pricing for all price-applicable components is required for a product to be activable/publishable. Note that pricing components are derived from corresponding settings, for example if the product rate is set to be priced per booking then a relevant per-booking pricing rule should exist.
Note (1): make sure a complete list of rules is always sent on update as otherwise omitted rules will be erased.
Note (2): price rules are immutable. Once created, rules can’t be modified. If you want to modify a price item make sure you omit price rule ID (this will cause the said rule to be deactivated) and supply a new ID-less rule with all the necessary settings. The new rule will be inserted on top of existing one. Specifying duplicate rules for the same price item (same currency, same price catalog, same pricing category, same base/schedule and so on) will cause rejection.
Dimensions of pricing rules
Bókun's pricing rules have the following dimensions:
- price catalog. This is a feature modeled after paper catalogs. The general idea behind catalogs is to have the ability to have different prices for different sales channels if needed
- currency. Specified for each product separately but also linked against price catalog
- rate
- pricing category (if priced per person, otherwise if per booking only one price can be set without involving pricing categories)
- tier (if priced per person and tiered pricing is enabled), configured at rate level. Note that different price can be set for each pricing category / tier combination)
Apart from dimensions listed above, these are the entities for which prices can be specified:
- product itself
- extra. Note that extras can also be per person and per booking (configured at each rate for each extra), regardless whether product is per person or not. Extras can be price inclusive (rule is not needed) or price exclusive (rule is needed).
- pickup. Same as extras, per person / per booking is configured at rate level, independent from product per person / per booking settings. Price inclusive / exclusive configured at rate level for each pickup
- dropoff. A separate set of settings, same as for pickups & extras
Note: tiers only apply to products and not extras/pickups/dropoffs. Rates, price catalogs, currencies and pricing categories though, can be applied to all 4 types.
Attributes of ExperiencePricingDto
Attribute JSON path | Data type | Mandatory | Settable | Notes |
experiencePriceRules | Array of ExperiencePriceRuleDto | ✓ | ✓ | Price rules pertaining to pricing categories, tiers and per-booking prices |
extraPriceRules | Array of ExtraPriceRuleDto | ✓ | Prices pertaining to extras, as configured at rate level | |
pickupPriceRules | Array of PickupPriceRuleDto | ✓ | Prices pertaining to passenger pickups, as configured at rate level | |
dropoffPriceRules | Array of DropoffPriceRuleDto | ✓ | Prices pertaining to passenger dropoffs, as configured at rate level | |
priceCatalogCurrencies | Array of ExperiencePriceCatalogCurrenciesDto | ✓ | ✓ | Specifies which price catalogs are linked to each product, as well as which currency(-ies) are applicable for said catalog/product |
Common attributes shared by ExperiencePriceRuleDto, ExtraPriceRuleDto, PickupPriceRuleDto and DropoffPriceRuleDto
Attribute JSON path | Data type | Mandatory | Settable | Notes |
id | long | Should only be supplied if any given rule should be kept as-is. Must be omitted on creation of a new rule | ID numbering is independent and may clash among different types (extra, pickup and so on) | |
rate | IdExternalIdDto | ✓ | ✓ | Should reference experience product rate either using Bokun-local rate ID or external ID |
created | TimestampDto | Date/time this rule was created. Read-only attribute. Expressed as a number of milliseconds since January 1, 1970, 00:00:00 UTC | ||
priceCatalogId | long | ✓ | ✓ | Which price catalog is this rule referencing? |
currency | string | ✓ | ✓ | ISO 4217 currency code. Currency for this price rule. Note that currency must be supported by Bokun |
amount | string | ✓ | ✓ | Price amount for this rule. Can’t be negative or excessive. Refer to BigDecimal format for more details |
priceScheduleId | long | ✓ | If set, this will refer to a specific price schedule. Otherwise this will treated as a “base” rule (applicable always) | |
pricingCategoryId | long | Only if rule applies to a specific pricing category (as opposed to per-booking rules) | ✓ | Should refer to a pricing category ID which is assigned to the product |
Specific ExperiencePriceRuleDto attributes
Attribute JSON path | Data type | Mandatory | Settable | Notes |
tierId | long | Mandatory if rule pertains to tiered pricing | ✓ | ID of tier. Reference to ExperienceRateTierDto::id |
Note: at the moment it is not possible to create a product with tiered pricing and set all the prices in one request as tierId is only available after rate creation. The workaround is to create the product with according rate setup using the first/create request and then set the prices with a subsequent update request.
Specific ExtraPriceRuleDto attributes
Attribute JSON path | Data type | Mandatory | Settable | Notes |
extraId | IdExternalIdDto | ✓ | ✓ | ID of extra |
Specific PickupPriceRuleDto attributes
None
Specific DropoffPriceRuleDto attributes
None
Attributes of ExperiencePriceCatalogCurrenciesDto
Attribute JSON path | Data type | Mandatory | Settable | Notes |
priceCatalogId | long | ✓ | ✓ | Price catalog id ( PriceCatalogDto::id) |
currencies | Array of strings | ✓ | ✓ | Specifies which currency(-ies) is/are applicable for this product and price catalog combo. Each currency string must be of ISO 4217 format and supported by Bokun |
defaultCurrency | string | ✓ | ✓ | One of supplied currencies which should be marked as the default currency for this product/catalog |