Connector API
Search
K

Rates

Get all rates

Returns all rates (pricing setups) and rate groups (condition settings) of the default service provided by the enterprise. Note this operation uses Pagination and supports Portfolio Access Tokens.

Request

[PlatformAddress]/api/connector/v1/rates/getAll
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"EnterpriseIds": [
"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"4d0201db-36f5-428b-8d11-4f0a65e960cc"
],
"ServiceIds": [
"bd26d8db-86da-4f96-9efc-e5a4654a4a94"
],
"RateIds": [
"ed4b660b-19d0-434b-9360-a4de2ea42eda"
],
"UpdatedUtc": {
"StartUtc": "2022-10-15T00:00:00Z",
"EndUtc": "2022-10-20T00:00:00Z"
},
"ExternalIdentifiers": [
"Rate-001",
"Rate-002"
],
"ActivityStates": [
"Active"
],
"Extent": {
"Rates": true,
"RateGroups": true,
"AvailabilityBlockAssignments": true
},
"Limitation": { "Count": 10 }
}
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
EnterpriseIds
array of string
optional, max 1000 items
Unique identifiers of the Enterprises. If not specified, the operation returns data for all enterprises within scope of the Access Token.
ServiceIds
array of string
required, max 1000 items
Unique identifiers of the Services from which the rates are requested.
RateIds
array of Rates
optional, max 1000 items
Unique identifiers of the requested Rates.
UpdatedUtc
optional, max length 3 months
Interval in which the Rates were updated.
ExternalIdentifiers
array of string
optional, max 1000 items
Identifiers of Rate from external systems.
ActivityStates
array of string Activity state
optional
Whether to return only active, only deleted, or both types of record. If not specified, both active and deleted will be returned.
Extent
required
Extent of data to be returned.
Limitation
required
Limitation on the quantity of data returned.

Rate extent

Property
Type
Contract
Description
Rates
bool
optional
Whether the response should contain rates.
RateGroups
bool
optional
Whether the response should contain rate groups. Deprecated!
AvailabilityBlockAssignments
bool
optional
Whether the response should contain availability block assignments.

Response

{
"Rates": [
{
"BaseRateId": null,
"BusinessSegmentId": null,
"GroupId": "c8b866b3-be2e-4a47-9486-034318e9f393",
"Id": "ed4b660b-19d0-434b-9360-a4de2ea42eda",
"ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94",
"IsActive": true,
"IsEnabled": true,
"IsPublic": true,
"Name": "Fully Flexible",
"ShortName": "FF",
"ExternalNames": {
"en-US": "Long Stay Flexible Rate"
},
"ExternalIdentifier": "D001"
}
],
"RateGroups": [
{
"Id": "c8b866b3-be2e-4a47-9486-034318e9f393",
"ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94",
"IsActive": true,
"Name": "Default",
"ExternalIdentifier": "RG001"
}
],
"AvailabilityBlockAssignments": [
{
"RateId": "ed4b660b-19d0-434b-9360-a4de2ea42eda",
"AvailabilityBlockId": "12806ae8-9c15-44c7-9a44-afae01289928"
}
]
}
Property
Type
Contract
Description
Rates
array of Rate
required
Rates of the default service.
RateGroups
array of Rate group
required
Rate groups of the default service. Deprecated!
AvailabilityBlockAssignments
optional
Shows which rates relate to which availability blocks.
Cursor
string
optional
Unique identifier of the item one newer in time order than the items to be returned. If Cursor is not specified, i.e. null, then the latest or most recent items will be returned.

Add rates

Adds rates to the enterprise. Note this operation supports Portfolio Access Tokens. Rate type of AvailabilityBlock cannot be created via this operation.

Request

[PlatformAddress]/api/connector/v1/rates/add
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"EnterpriseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"Rates":[
{
"ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94",
"RateGroupId": "b9f25a45-9b9a-4b33-99bd-b06f008eb6f5",
"IsEnabled": true,
"Type": "Public",
"AccountingCategoryId": "3620c660-a4ec-4e0f-a0bc-b06f008eb8bf",
"Names": { "EN": "My rate" },
"ExternalIdentifier": "D001",
"PricingType": "DependentRatePricing",
"Pricing": {
"DependentRatePricing": {
"BaseRateId": "1a1ddd3b-e106-4a70-aef1-54a75b483943",
"RelativeAdjustment": 0.15,
"AbsoluteAdjustment": 10.0
}
}
}
]
}
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
EnterpriseId
string
optional
Unique identifier of the Enterprise. Required when using a Portfolio Access Token, ignored otherwise.
Rates
array of Rate parameters
required, max 1000 items
Information about rates to be created.

Rate parameters

Property
Type
Contract
Description
ServiceId
string
required
Unique identifier of the Service.
RateGroupId
string
required
Unique identifier of the Rate group under which rate is assigned.
IsEnabled
bool
optional
Whether the rate is available to customers. False will be used as a default when not provided.
Type
required
Type of the rate.
AccountingCategoryId
string
optional
Unique identifier of the Accounting category the rate belongs to.
BusinessSegmentId
string
optional
Unique identifier of the Business segment.
Names
required
All translations of the name of the rate.
ShortNames
optional
All translations of the short name of the rate.
ExternalNames
optional
All translations of the external name of the rate.
Descriptions
optional
All translations of the description.
ExternalIdentifier
string
optional, max 255 characters
Identifier of the rate from external system.
PricingType
required
Discriminator in which field inside Pricing contains additional data.
Pricing
required
Contains additional data about pricing of the rate.

Rate pricing parameters

Property
Type
Contract
Description
BaseRatePricing
optional
Additional data for rate with base rate pricing.
DependentRatePricing
optional
Additional data for rate with dependent rate pricing.

Base rate pricing parameters

Property
Type
Contract
Description
Amount
required
Unit amount of the product. Note this overrides any previously defined amount.
NegativeOccupancyAdjustment
decimal
optional
This is the amount added to the price when occupancy of the space is less than the Space Category Capacity. To provide a discount price for under-occupancy, simply use a negative value.
ExtraOccupancyAdjustment
decimal
optional
This is the amount added to the price when the Space Category Capacity is exceeded.

Dependent rate pricing parameters

Property
Type
Contract
Description
BaseRateId
string
required
Unique identifier of the rate on which this dependent rate is based.
RelativeAdjustment
decimal
optional
This value is multiplied by the base rate to calculate an adjustment added to the base rate, e.g. a value of 1.0 means add 100% of the base rate to the base rate, effectively doubling the price. To subtract an amount, simply use a negative value, e.g. a value of -0.1 means subtract 10% of the base rate from the base rate.
AbsoluteAdjustment
decimal
optional
This value is simply added to the base rate to obtain the new price. To subtract an amount, use a negative value.

Response

{
"Rates": [
{
"Id": "ed4b660b-19d0-434b-9360-a4de2ea42eda",
"GroupId": "b9f25a45-9b9a-4b33-99bd-b06f008eb6f5",
"BaseRateId": "1a1ddd3b-e106-4a70-aef1-54a75b483943",
"BusinessSegmentId": null,
"ServiceId": "bd26d8db-86da-4f96-9efc-e5a4654a4a94",
"IsActive": true,
"IsEnabled": true,
"IsPublic": true,
"Type": "Public",
"Name": "My rate",
"ShortName": "FF",
"ExternalNames": {
"en-US": "Long Stay Flexible Rate"
},
"ExternalIdentifier": "D001"
}
]
}
Property
Type
Contract
Description
Rates
array of Rate
required
Rates that have been added.

Rate

Property
Type
Contract
Description
Id
string
required
Unique identifier of the rate.
GroupId
string
required
Unique identifier of Rate group where the rate belongs.
BaseRateId
string
optional
Unique identifier of the base Rate.
BusinessSegmentId
string
optional
Unique identifier of the Business segment.
ServiceId
string
required
Unique identifier of the Service.
IsActive
boolean
required
Whether the rate is still active.
IsEnabled
boolean
required
Whether the rate is currently available to customers.
IsPublic
boolean
required
Whether the rate is publicly available.
Type
Rate type
required
Type of the rate
Name
string
required
Name of the rate (in the default language).
ShortName
string
optional
Short name of the rate (in the default language).
ExternalNames
optional
All translations of the external name of the rate.
Description
optional
All translations of the description of the rate.
ExternalIdentifier
string
optional, max 255 characters
Identifier of the rate from external system.

Rate group

Property
Type
Contract
Description
Id
string
required
Unique identifier of the group.
ServiceId
string
required
Unique identifier of the Service.
IsActive
boolean
required
Whether the rate group is still active.
Name
string
required
Name of the rate group.
ExternalIdentifier
string
optional, max 255 characters
Identifier of the rate group from external system.

Availability block assignment

Property
Type
Contract
Description
RateId
string
required
Unique identifier of the Rate.
AvailabilityBlockId
string
required
Unique identifier of the Availability Block.

Get rate pricing

Returns prices for a given rate for a specified time interval. Prices will be returned for all service time units that the specified time interval intersects. So, for example, an interval 1st Jan 23:00 UTC - 1st Jan 23:00 UTC will result in one price for 2nd Jan, while Interval 1st Jan 23:00 UTC - 2nd Jan 23:00 UTC will result in two prices for 2nd Jan and 3rd Jan (assuming a time unit period of "Day"). UTC timestamps must correspond to the start boundary of a time unit, e.g. 00:00 converted to UTC for a time unit of "Day". Other timestamps are not permitted. The maximum size of time interval depends on the service's time unit: 367 hours if hours, 367 days if days, or 24 months if months.
The price in the response is dependent on the enterprise's pricing setting. If the enterprise is set to a Gross pricing environment, then the price returned is the gross price (inclusive of tax). If the enterprise is set to a Net pricing environment, the price returned is the net price (excluding tax). Note this operation supports Portfolio Access Tokens.

Request

[PlatformAddress]/api/connector/v1/rates/getPricing
{
"ClientToken": "E0D439EE522F44368DC78E1BFB03710C-D24FB11DBE31D4621C4817E028D9E1D",
"AccessToken": "C66EF7B239D24632943D115EDE9CB810-EA00F8FD8294692C940F6B5A8F9453D",
"Client": "Sample Client 1.0.0",
"RateId": "ed4b660b-19d0-434b-9360-a4de2ea42eda",
"FirstTimeUnitStartUtc": "2022-01-01T23:00:00.000Z",
"LastTimeUnitStartUtc": "2022-01-03T23:00:00.000Z"
}
Property
Type
Contract
Description
ClientToken
string
required
Token identifying the client application.
AccessToken
string
required
Access token of the client application.
Client
string
required
Name and version of the client application.
RateId
string
required
Unique identifier of the Rate whose prices should be returned.
FirstTimeUnitStartUtc
string
required
Start of the time interval, expressed as the timestamp for the start of the first time unit, in UTC timezone ISO 8601 format.
LastTimeUnitStartUtc
string
required
End of the time interval, expressed as the timestamp for the start of the last time unit, in UTC timezone ISO 8601 format. The maximum size of time interval depends on the service's time unit: 367 hours if hours, 367 days if days, or 24 months if months.

Response

{
"Currency": "EUR",
"BaseAmountPrices": [
{
"Currency": "EUR",
"NetValue": 93.46,
"GrossValue": 100.00,
"TaxValues": [
{
"Code": "DE-2020-1-L",
"Value": 6.54
}
],
"Breakdown": {
"Items": [
{
"TaxRateCode": "DE-2020-1-L",
"NetValue": 93.46,
"TaxValue": 6.54
}
]
}
},
{
"Currency": "EUR",
"NetValue": 93.46,
"GrossValue": 100.00,
"TaxValues": [
{
"Code": "DE-2020-1-L",
"Value": 6.54
}
],
"Breakdown": {
"Items": [
{
"TaxRateCode": "DE-2020-1-L",
"NetValue": 93.46,
"TaxValue": 6.54
}
]
}
}
],
"CategoryAdjustments": [
{
"AbsoluteValue": 0,
"CategoryId": "34c29e73-c8db-4e93-b51b-981e42655e03",
"ParentCategoryId": null,
"RelativeValue": 0.2
},
{
"AbsoluteValue": 50,
"CategoryId": "a0a7a5c5-c4ef-494a-8b34-6cca97629076",
"ParentCategoryId": "34c29e73-c8db-4e93-b51b-981e42655e03",
"RelativeValue": 0
}
],
"CategoryPrices": [
{
"CategoryId": "e3aa3117-dff0-46b7-b49a-2c0391e70ff9",
"AmountPrices": [
{
"Currency": "EUR",
"NetValue": 93.46,
"GrossValue": 100.00,
"TaxValues": [
{
"Code": "DE-2020-1-L",
"Value": 6.54
}
],
"Breakdown": {
"Items": [
{
"TaxRateCode": "DE-2020-1-L",
"NetValue": 93.46,
"TaxValue": 6.54
}
]
}
},
{
"Currency": "EUR",
"NetValue": 93.46,
"GrossValue": 100.00,
"TaxValues": [
{
"Code": "DE-2020-1-L",
"Value": 6.54
}
],
"Breakdown": {
"Items": [
{
"TaxRateCode": "DE-2020-1-L",
"NetValue": 93.46,
"TaxValue": 6.54
}
]
}
}
]
}
],
"TimeUnitStartsUtc": [
"2022-01-01T23:00:00Z",
"2022-01-02T23:00:00Z",
"2022-01-03T23:00:00Z"
]
}
Property
Type
Contract
Description
Currency
string
required
ISO-4217 code of the Currency.
TimeUnitStartsUtc
array of string
required
Set of all time units covered by the time interval; expressed in UTC timezone ISO 8601 format.
BaseAmountPrices
array of Amount value
required
Base prices of the rates for each time unit covered by the time interval.
CategoryPrices
required
Resource category prices.
CategoryAdjustments
required
Resource category adjustments.
RelativeAdjustment
decimal
required
Specific amount which shows the difference between this rate and the base rate.
AbsoluteAdjustment
decimal
required
Relative amount which shows the difference between this rate and the base rate.
EmptyUnitAdjustment
decimal
required
Price adjustment for when the resource booked with this rate is not full to capacity.
ExtraUnitAdjustment
decimal
required
Price adjustment for when the resource booked with this rate exceeds capacity.

Resource category pricing

Property
Type
Contract
Description
CategoryId
string
required
Unique identifier of the Resource category.
AmountPrices
array of Amount value
required
Prices of the rate for the resource category in the covered dates.

Resource category adjustment

Property
Type
Contract
Description
CategoryId
string
required
Unique identifier of the adjustment Resource category.
ParentCategoryId
string
optional
Unique identifier of the parent Resource category that serves as a base price for the current category.
RelativeValue
number
required
Relative value of the adjustment (e.g. 0.5 represents 50% increase).
AbsoluteValue
number
required
Absolute value of the adjustment (e.g. 50 represents 50 EUR in case the rate currency is EUR).

Update rate price