Das Planyo API ermöglicht es Ihnen, erweiterte Funktionen auszuführen und das Planyo-Reservierungssystem zu automatisieren (z. B. den Import von Ressourcendaten und –fotos in Ihre Site oder führen Sie automatische Reservierungen durch). Um API zu benutzen, müssen Sie mit einer Programmiersprache vertraut sein, etwa PHP, Java, Ruby oder ASP.NET.
API Key Click this button to get your API key. You will need it to authenticate all calls made to the API
API calls are by default only protected by your secret API key.
Never use this key in client-side scripts (e.g. javascript) and make sure it's well protected. Use this key only with the SSL-protected endpoint listed below. For extra security, API keys can be protected by only allowing calls from specified IP addresses and/or by allowing calls only to specific methods. Another recommended security measure is usage of the hash key. If enabled, all calls must include the parameter
hash_timestamp with the current timestamp at the time of making the call AND the parameter
hash_key which is the MD5 hash of a text which includes both the secret hash key and timestamp. See the
Request format section below for details.
The API uses the REST request format: a simple GET or POST HTTP action. The REST end point URL is:
http://planyo.com/rest/
Here's a sample test request:
http://planyo.com/rest/?method=api_test
Required parameters
All API requests require the following parameters:
method - this is the method being called
api_key - your API key (note: the API key is required for all methods except
api_test).
Click here to get your key
Other required parameters - only when the hash key is enabled
hash_timestamp int - this is the current timestamp (seconds since the Unix Epoch: January 1 1970 00:00:00 GMT)
hash_key string - MD5 hash of the concatenated string containing: the hash key,
hash_timestamp and
method parameters (without any separating character). Make sure the timestamp included in the hash key calculation is exactly the same as the
hash_timestamp parameter and that the time is correct. For example, a PHP call can be made as follows in case your API key is ABC and the hash key is DEF:
$hash_timestamp = time();
$output = file_get_contents("http://planyo.com/rest/?method=get_site_info&api_key=ABC&hash_timestamp=" . $hash_timestamp . "&hash_key=" . md5("DEF" . $hash_timestamp . "get_site_info"))
Optional parameters
language - by specifying a 2-letter (ISO 639-1) language code (all capital letters e.g.
EN,
DE,
FR,
ES,
IT) you can change the language of the text values returned in the
data key
The Planyo API uses JSON (JavaScript Object Notation) as the response format. This is one of the most popular data formats (more info about this format at
json.org) fully supported by all popular scripting languages. The response uses a named array for the output data with text-based keys.
Successful responses
Here's a sample response (returned by the
api_test method):
{"data":"API Test Response","response_code":0,"response_message":"Method api_test executed successfully."}
Successful responses will contain the response data in the
data key. This is usually another named array but in the response above, it's a simple string 'API Test response'.
The
response_code key will always contain the value of
0 (success) and
response_message will say
Method xyz executed successfully.
Failure responses
Failure responses will contain one of the following failure codes in the
response_code key:
1 - authentication error (e.g. invalid API key) or invalid method
3 - invalid input data
4 - other error from the method you're calling
5 - call rejected because of API overuse; please see below for the allowed limits
6 - fatal error (could occur e.g. if the call takes too long to complete)
The following API methods are currently available:
Reservations
add_reservation_payment Adds a payment for a reservation. You may NOT pass customer's credit card numbers in any of the fields. Planyo doesn't keep any credit card numbers on its servers.can_make_reservation Returns true if reservation can be made or false if it's not possible. A reservation may not be possible because of lack of availability or because of other constraints such as required start/end weekday, not enough free time after previous rental etc.delete_custom_property Deletes a property by name. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations.delete_reservation Permanently deletes a reservation. Warning: this action cannot be undone.do_reservation_action Call to perform an administrative action (such as confirmation or cancellation) on a reservationget_custom_property Returns value of a property. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations. Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI.get_promotable_reservations Lists all waiting list requests which can be promoted to a valid reservation. You must specify the ID of an existing waiting list placeholder vacation (which you can get by calling list_vacations) that was automatically created by Planyo after the resource was made available (a reservation was cancelled or vacation was removed).get_rental_price Returns the price of a rental for given resource and start/end times. Price is returned even if resource is not available in given period (because of vacations defined or existing reservations).Note that if you want to fetch prices for multiple periods (up to 50), you can pass optional parameters start_time_x and end_time_x (e.g. start_time_2=...&end_time_2=...&start_time_3=...&end_time_3=....) where x is in range from 2 to 50. In such case the output will include extra_times with the prices for the extra times. You can also customize result number x by passing quantity_x, resource_id_x, shopping_cart_position_x, rental_prop_x_YYYget_reservation_actions This function lists reservation actions (events), such as modifications, cancellations etc. You can optionally narrow down the events returned to a specific reservation ID, to all reservations of a specific customer, to specific time range, or to a specific event.list_payments List payments made for your reservations. You can specify a number of parameters to filter the results.list_reservations Lists all reservations that either start within given time period or that were entered into the system within given time period (when list_by_creation_date is true). A maximum of 500 reservations will be listed. For further items use the 'page' parameter.make_reservation Enters a new reservation into the system. The ID of the new reservation is available in 'reservation_id' in case of success. If you're using the PRO-COMM payment model, the commission will be calculated for API-entered reservations.modify_reservation Make modifications to an existing reservation using this function. You can modify the resource, rental time, quantity, and the custom reservation form items. The parameters which you don't want to modify should not be passed.recalculate_price Use this function to recalculate the price of an existing reservation. A recalculation may be needed for example if the pricing manager rules were changed since the reservation was made, or if a voucher was applied at a later time, etc.reservation_search Finds all reservations containing text specified in the query parameter (this works in the same was as the Search tab in the admin panel). You can search for one or more of the following: first and/or last name, login name, user ID, reservation ID, email address, phone number, resource name.search_reservations_by_form_item Finds all reservations whose form item (name specified in item_name) has the specified value. This is useful especially for hidden form items which can have a special meaning to you, e.g. booking ID in an external system. This function will return max 500 reservations.set_custom_properties Sets new values for multiple properties (max 50), of the type specified in the type parameter -- Planyo allows assigning custom properties to users, sites, resources and reservations. The property names (comma-separated) must be specified in the names parameter, and the values should be passed using the specified parameter names, e.g. if you set names to a,b,c then the values are passed as: ...&names=a,b,c&a=1&b=2&c=3Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI. Note that normally for resource properties the language parameter should not be passed unless you're setting a language-specific property such as description.set_custom_property Sets a new value for the property. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations. Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI. Note that normally for resource properties the language parameter should not be passed unless you're translating a property such as description to another language. In order to translate a resource name to a different language, use the special parameter 'hidden_name': type=resource&name=hidden_nameset_reservation_color Set a new color for the reservation. Currently the following colors can be used: #A8314F,#33FF33,#4D4DFF,yellow,#B84DFF,#999999,#81FCF6,#FFBAF1,#DADAD2,#ECDC81,#CEF0FF,#D1FFB3,#FFA4A4set_reservation_price Set a custom price for a reservation. This does the same as changing the price by an admin on the reservation details page.Availability
add_vacation Adds a new one-time vacation for given resource or entire Planyo site. To add weekly vacations, see the function set_weekly_schedule.can_make_reservation Returns true if reservation can be made or false if it's not possible. A reservation may not be possible because of lack of availability or because of other constraints such as required start/end weekday, not enough free time after previous rental etc.get_ical_feed_url Use this function to get the URL of an iCal feed for a metasite, site, resource or selected resources. You can also filter the iCal feed by the value of a reservation form item. See the list_all parameter if you'd like to make a single call and get feeds for all of your resources.get_resource_usage This function will return usage/availability information of given resource (or entire site) for specified period of time. Note that the output is minimized, so only periods with usage (reservations or vacations) will be returned.get_resource_usage_for_month This function will return usage/availability information of given resource (or entire site) for an entire month.get_weekly_schedule Use this function to get a listing of all weekly vacations of a resource (or all resources; see the resource_id parameter) or to get a listing of all working hours during the week.is_resource_available Returns resource availability for given time period. Please note that making a reservation may be impossible even if the resource is available. This may be caused by additional constraints such as required start/end weekday, not enough free time after previous rental etc. Use can_make_reservation to find out if a reservation can be made for given start/end time taking under consideration both availability and other constraints. In case the resource is a package which cannot be reserved because of a resource which is in package contents, its ID will be returned in unavailable_resource_id.list_vacations Lists all vacations within specified time range. You can specify either site_id or resource_id to get site-wide vacations in the first case and resource-specific vacations in the second case. Pass resource_id=all and include_site_vacations to list all vacations.resource_search Searches for available resources for given time period. The results can be returned as raw data or as HTML code depending on the value of the optional 'output' parameter.set_resource_availability Use this function to set availability in bulk (for a number of days or time units). Availability is set exactly in the same way as in the backend in Schedule&Reports / Availability calendar -- you can both increase and decrease the available quantity. Please note that you cannot increase the quantity beyond the number of NON-RESERVED units. Trying to do so will make as many units available as possible and will generate a warning.set_weekly_schedule Use this function to specify the regular working / unavailable hours for given resource (or all resources; see the resource_id parameter). One way to use this function is to determine the working hours of a resource. In this scenario, set default to 0 and pass all available periods using the av-XXX parameters. Example: default=0&av-mon-0800-1800=1&av-wed-0800-1800=1 (resource is available ONLY on Mondays and Wednesdays between 8am and 6pm). You can also use this function using the standard Planyo logic, that is, assuming the resource is always available (but within the working hours determined in resource settings) and specifying a list of periods when the resource should not be available for reservations. Example: default=1&av-mon-1200-1400=0&av-tue-1200-1400=0&av-wed-1200-1400=0&av-thu-1200-1400=0&av-fri-1200-1400=0 (resource is not available during lunch hours on weekdays, lunch hours are 12:00 until 14:00). This function will not modify resource's working hours but will remove all existing recurring weekly vacations and will create new vacations based on the parameters passed.Additional products
add_custom_product Use this function to add a new custom product to a reservation. Note that custom products are different from regular additional products in that they have no fixed definition. Each time they are added the name and price must be specified. As with the additional products, these custom products will also be listed in the invoice.get_reservation_products This method returns detailed information about the additional products reserved for given reservation ID.modify_additional_product Use this function to make modifications to an existing additional product. You can modify any number of fields in a single callremove_additional_product Removes an existing additional product. WARNING: removing a product will also remove its usage from all reservations where the product was used; this operation cannot be undone. The extra parameters (site_id, product_id_md5) are required for verification purposes.remove_custom_product Removes an existing custom product. You can get the custom product ID from the calls to either add_custom_product or get_reservation_productsset_product_usage_for_reservation Use this function to add or remove additional products for given reservation ID. This won't trigger notifications, web hooks or price recalculation. See set_reservation_products for this functionality or if you'd like to set usage of all products for given reservation in a single call.set_reservation_products Use this function to set/reset the usage of all the additional products for given reservation. Existing product usage will be erased (see get_reservation_products if you need to get all products reserved so far). This function will trigger notifications (if configured), web hooks and price recalculation (if requested).Resources
add_custom_property_definition Adds a new custom property definition to your site or metasite. This will show the new property in resource settings / general info in the backend UI (for resource properties), or in site settings / company info (for site properties). Custom property definitions are required if you need them as search criteria or resource listing filters. If the resource property (or any of the aliases) already exists, it will not be overridden.add_resource Use this function to add a new resource to your Planyo site. The new resource is created by making an exact copy of an existing resource (it can be an unpublished resource which you can keep on your site free of charge just for this purpose), including custom resource properties (images are not duplicated). You can additionally use optional parameters to override base resource's settings. The only required parameter from this group is the name of the new resource.delete_custom_property Deletes a property by name. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations.get_bundle_contents This function returns the list of resources and coupons included in a bundleget_custom_property Returns value of a property. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations. Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI.get_form_items Returns reservation form items for given resource (if resource_id is specified) or for the global form (if resource_id is not specified) or the all possible reservation forms of the site, including both the global form and resource-specific forms (if resource_id has the special value of -1). get_ical_feed_url Use this function to get the URL of an iCal feed for a metasite, site, resource or selected resources. You can also filter the iCal feed by the value of a reservation form item. See the list_all parameter if you'd like to make a single call and get feeds for all of your resources.get_package_contents This function returns detailed information about a package, including package type and the contents (resources included in the package)get_resource_info Returns information for given resource, including photos and resource-specific properties defined in the admin panel in: Site settings / Custom resource propertiesget_resource_pricing Returns complete pricing information for all resources of a site. Pricing is returned in two separate arrays: one with the default prices and one with the additional pricing rules. Keys of both arrays are resource IDs.get_simplified_daily_pricing Use this function for day-based resources if you need to get daily pricing for a range of dates (max 2 years). This function is mostly used for accommodations in order to convert the prices defined in Pricing Manager to prices understood by channel managers (price for given day and for given number of persons). Note that Pricing Manager is way more complex than the daily price format normally used by channel managers and other accommodation sites so it's likely that if you're using more advanced rules of Pricing Manager you'll see some warnings in the output plus the daily price returned may be different than the actual price calculated by Planyo.get_simplified_daily_restrictions Use this function if you need to get daily restrictions for a range of dates (max 2 years). This function is mostly used for accommodations in order to convert the restrictions defined in seasonal settings and in time-related settings to restrictions understood by channel managers. Note that Planyo is capable of having more restrictions which will not be returned by this function, e.g. the ones defined in Pricing Manager checking for a wide number of conditions (using the UNAVAILABILITY MESSAGE values instead of prices).list_resources Returns resources defined in a Planyo site or meta site along with additional information and photos. You can specify a resource filter. Note: old name of this function was get_all_resources. You can still use that function name instead.modify_resource Use this function to make modifications to an existing resource. You can modify any number of fields in a single callremove_resource Removes an existing resource. WARNING: all existing reservations for the resource will be also removed and this operation cannot be undone. The extra parameters (resource_name, site_id, resource_id_md5) are required for verification purposes.set_custom_properties Sets new values for multiple properties (max 50), of the type specified in the type parameter -- Planyo allows assigning custom properties to users, sites, resources and reservations. The property names (comma-separated) must be specified in the names parameter, and the values should be passed using the specified parameter names, e.g. if you set names to a,b,c then the values are passed as: ...&names=a,b,c&a=1&b=2&c=3Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI. Note that normally for resource properties the language parameter should not be passed unless you're setting a language-specific property such as description.set_custom_property Sets a new value for the property. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations. Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI. Note that normally for resource properties the language parameter should not be passed unless you're translating a property such as description to another language. In order to translate a resource name to a different language, use the special parameter 'hidden_name': type=resource&name=hidden_nameset_package_contents Use this function to make a resource into a pakcage and set package type and contents, or to make a package into a regular resource (by setting package_type=none)set_resource_admin Use this function to set a new resource administrator. You cannot make into a resource admin a user who is a moderator or resource admin of another unrelated Planyo site.If the user has been added by an admin / API call or is already a moderator or resource admin of the site, they will be automatically assigned as resource admin. Otherwise, a confirmation email will be sent to the user's email address and the user will be assigned as resource admin once they confirm the action. Check the status output field to find out if the assignment was immediate. Note that the user should have a login and password associated with their Planyo account.set_resource_pricing This function sets the pricing for given resource. With a single call you can set prices for all the rules of Pricing Manager. Note that the rule IDs passed in the parameters rule_price_type_xxx and rule_price_value_xxx can be numeric (returned by get_resource_pricing) or they can be in form of the permatag visible in Pricing Manager when you click on the Reorder button.set_unit_names Sets the unit names of a resource. The number of units must be equal to the quantity of the resource. Use the function list_resources or get_resource_info in order to fetch existing unit names.Resource units
get_unit_property Returns value of a custom unit property. Unit properties can have different values at different dates/times (e.g. odometer reading at rental start/end) and so the values are always retrieved for a specific time.set_unit_names Sets the unit names of a resource. The number of units must be equal to the quantity of the resource. Use the function list_resources or get_resource_info in order to fetch existing unit names.set_unit_property Sets a custom unit property. Unit properties can have different values at different dates/times (e.g. odometer reading at rental start/end) and so the values are always set for a specific time.Sites
add_custom_property_definition Adds a new custom property definition to your site or metasite. This will show the new property in resource settings / general info in the backend UI (for resource properties), or in site settings / company info (for site properties). Custom property definitions are required if you need them as search criteria or resource listing filters. If the resource property (or any of the aliases) already exists, it will not be overridden.add_site This function can only be used for metasite api keys. Use this function to add a new site to your metasite. The new site is created by making a copy of an existing site. You can additionally use optional parameters to override base site's settings.add_site_moderator Use this function to add a new moderator to a site. You cannot make into a moderator a user who is a moderator or resource admin of another unrelated Planyo site.If the user has been added by an admin / API call or is already a moderator or resource admin of the site, they will be automatically assigned as moderator. Otherwise, a confirmation email will be sent to the user's email address and the user will be assigned as moderator once they confirm the action. Check the status output field to find out if the assignment was immediate. Note that the user should have a login and password associated with their Planyo account.add_url_to_admin_favorites Adds an easily-accessible favorite page to the backend of all the moderators and admins of a site or just for a specific user. This is the equivalent of clicking on the star icon on the title of any backend pagedelete_custom_property Deletes a property by name. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations.get_custom_property Returns value of a property. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations. Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI.get_form_items Returns reservation form items for given resource (if resource_id is specified) or for the global form (if resource_id is not specified) or the all possible reservation forms of the site, including both the global form and resource-specific forms (if resource_id has the special value of -1). get_ical_feed_url Use this function to get the URL of an iCal feed for a metasite, site, resource or selected resources. You can also filter the iCal feed by the value of a reservation form item. See the list_all parameter if you'd like to make a single call and get feeds for all of your resources.get_site_info Returns information for given site, including photos and site-specific properties defined in the admin panel in: Site settings / Custom resource propertieslist_reviews Use this function to list the reviews added by clients.list_sites Returns sites defined in a Planyo meta site along with additional information and photos. You can specify a site filter.modify_site Use this function to make modifications to an existing site. You can modify any number of fields in a single callset_custom_properties Sets new values for multiple properties (max 50), of the type specified in the type parameter -- Planyo allows assigning custom properties to users, sites, resources and reservations. The property names (comma-separated) must be specified in the names parameter, and the values should be passed using the specified parameter names, e.g. if you set names to a,b,c then the values are passed as: ...&names=a,b,c&a=1&b=2&c=3Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI. Note that normally for resource properties the language parameter should not be passed unless you're setting a language-specific property such as description.set_custom_property Sets a new value for the property. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations. Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI. Note that normally for resource properties the language parameter should not be passed unless you're translating a property such as description to another language. In order to translate a resource name to a different language, use the special parameter 'hidden_name': type=resource&name=hidden_nameset_payment_gateway Sets the payment gateway to be used with given site (or metasite) along with the gateway-specific account ID.Seasons
modify_resource_season Modifies an existing season. You can use this function to modify one or more properties of the season. All the parameters representing season's properties are optional.remove_resource_season Removes a season (for a single resource or for entire Planyo site) identified by ID. The functions get_resource_seasons and add_resource_season return unique season IDs which are used to identify a specific season.Users
add_agent Use this function to add a new agent to a site. You cannot make into an agent a user who is a moderator or resource admin of another Planyo site.If the user has been added by an admin / API call or is already a moderator or resource admin of the site, they will be automatically assigned as agent. Otherwise, a confirmation email will be sent to the user's email address and the user will be assigned as agent once they confirm the action. Check the status output field to find out if the assignment was immediate. Note that the user should have a login and password associated with their Planyo account. If not, the warning output field will contain the appropriate info.add_site_moderator Use this function to add a new moderator to a site. You cannot make into a moderator a user who is a moderator or resource admin of another unrelated Planyo site.If the user has been added by an admin / API call or is already a moderator or resource admin of the site, they will be automatically assigned as moderator. Otherwise, a confirmation email will be sent to the user's email address and the user will be assigned as moderator once they confirm the action. Check the status output field to find out if the assignment was immediate. Note that the user should have a login and password associated with their Planyo account.add_user Use this function to insert a new user associated with your Planyo site. You can optionally specify a login/password and assign any number of user-specific properties. Note: for existing users, custom user properties (prop_user_xyz) and personal details will be updated, the login data will not be overridden.delete_custom_property Deletes a property by name. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations.get_custom_property Returns value of a property. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations. Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI.get_user_data Returns details of a user. The users which can be found are those who made at least one reservation, were created by the admins, or they must administer the site (as main administrator, resource admin or moderator). You must pass either the email address or the user ID.list_users Returns all users with at least one reservation (unless list_created_by_admin is set to true in which case users created by the admins are returned, also with no reservations). You can specify a user filter. A single API call returns at most 1000 results. If you want to get further results, change the page parameter. Note: old name of this function was get_all_users. You can still use that function name instead.modify_user Use this function to modify an existing user's data. The user must be identified by one of the following fields: email, user_id, user_login. Access to modify user's data is possible only when the user was either added manually or via CSV import by one of your admins, or if they made at least one reservation with your site/metasite. On top of that you cannot modify users who made reservations with sites which you don't administer (or which are not a part of your metasite, if it's used). You can modify any number of fields in a single call.remove_user Deletes an existing user. A user can be deleted only if they have no reservations made for given Planyo site or if their only reservations have been cancelled and they have no other reservations outside of given Planyo site (or its parent metasite).set_custom_properties Sets new values for multiple properties (max 50), of the type specified in the type parameter -- Planyo allows assigning custom properties to users, sites, resources and reservations. The property names (comma-separated) must be specified in the names parameter, and the values should be passed using the specified parameter names, e.g. if you set names to a,b,c then the values are passed as: ...&names=a,b,c&a=1&b=2&c=3Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI. Note that normally for resource properties the language parameter should not be passed unless you're setting a language-specific property such as description.set_custom_property Sets a new value for the property. Properties can be of different types -- Planyo allows assigning custom properties to users, sites, resources and reservations. Please note that custom properties will be visible in the backend UI (for site administrators) unless the property name starts with 'hidden'. In such case the property will be usable only by the API and hidden everywhere in the UI. Note that normally for resource properties the language parameter should not be passed unless you're translating a property such as description to another language. In order to translate a resource name to a different language, use the special parameter 'hidden_name': type=resource&name=hidden_nameset_resource_admin Use this function to set a new resource administrator. You cannot make into a resource admin a user who is a moderator or resource admin of another unrelated Planyo site.If the user has been added by an admin / API call or is already a moderator or resource admin of the site, they will be automatically assigned as resource admin. Otherwise, a confirmation email will be sent to the user's email address and the user will be assigned as resource admin once they confirm the action. Check the status output field to find out if the assignment was immediate. Note that the user should have a login and password associated with their Planyo account.Shopping cart
create_cart Use this function to create a new shopping cart. Reservations created with the function make_reservation can then use this cart id to group reservations into a single cart.delete_cart Use this function to delete a shopping cart. Note that the shopping cart must be empty (no reservations in cart).get_cart_items Lists all reservations included in a shopping cart. A maximum of 500 reservations will be listed. For further items use the 'page' parameter.list_cart_payments List payments made for all reservations of a shopping cart. Note that in case of a shopping cart, payments are always assigned to specific reservations belonging to a shopping cart, even though the payment is made for all cart reservations.list_carts Lists shopping carts for a site or metasite. You can limit the carts listed to specific dates or only the ones that were checked out. A maximum of 500 carts will be listed. For further items use the 'page' parameter.Coupons and vouchers
apply_coupon Use this function to apply a coupon to an existing reservation. Coupon is passed as either the coupon_id or coupon_code parameter. Please note that coupons can be only applied to unconfirmed reservations.apply_voucher Use this function to apply a voucher to an existing reservation. Note that a voucher code can be also passed to make_reservation.create_voucher Use this function to create a new voucher. Vouchers can be limited to a metasite, to a single site, or to specific resources. Other settings correspond to the settings from the backend UI.list_coupon_types Lists coupons (coupon definitions) that can be purchased for your site.list_coupons Lists the purchased coupons. You can specify a number of parameters to filter the results.list_vouchers Lists vouchers. You can specify a number of parameters to filter the results, for example only so that the vouchers which can be used for a specific reservation parameters (dates/resource id) can be returned.modify_coupon Makes modifications to an existing coupon. The parameters which you don't want to modify should not be passed.modify_voucher Use this function to modify an existing voucher identified by voucher_id. Voucher IDs are returned by the functions list_vouchers and create_voucherNotifications
add_notification_callback Adds a webhook (callback) for specified event. This is the same as adding the URL to site settings / notifications / notification callbacks. Note that multiple webhooks are possible for a single event. If you leave callback_url empty, all webhooks for given event will be removed.remove_notification_callback Removes an existing webhook. You can also do this manually in site settings / notifications / notification callbacks.send_email_to_customer Allows you to send a message to the customer -- it's the same operation as clicking on Add new message on the reservation details page. The message being sent will be also registered in the history on that page for all administrators and the customer to see. Warning: this function will only work for sites with a custom SMTP server configured. If you use Planyo servers to send out your site's emails, this function will fail.Invoices
generate_invoice Generates a new invoice if one hasn't already been created for given reservation or if the reserved items have changed since the last invoice. This function will work only when using parent&corrective invoices.get_invoice_items Returns all products (invoice items) included with the reservation (same as products used on the invoice). The invoice items can include (besides reservations): additional products, custom products, payment surcharge. In case of the shopping cart, all shopping cart reservations will be included.list_invoices Lists invoices for given reservation or invoices generated in given period. This function only works with parent&corrective invoices. In case of multiple invoices, a maximum of 50 invoices will be listed. For further items use the 'page' parameter.Templates
process_template Template processor. This works the same way as in the email notifications or other templates. Depending on the context given by input parameters, you can use tags from Q204 and/or Q205. You can always use tags from Q206 and Q221 and the conditional tags from Q207. You must specify one of: site_id, resource_id or reservation_id to give appropriate context for the tags.Translations
list_translations Lists user-defined translations for given metasite, site or resource.set_translation Use this function to add text translations for your site or metasite. This is equivant to going to Settings / Customized translations. There you'll also find the existing text identifiers you can set with this function (S_xxx). Please note that you should always set the target language for the translation using the language parameter.Note: if you want to translate custom resource properties (such as resource description) or the resource name, use the function set_custom_property in order to set given custom resource property value for given language.
You'll find a PHP sample in the
list_resources,
get_event_times and
process_template functions. If you wish to make API calls from a webpage which your customers can visit, you will most likely need to add caching, otherwise you risk going over the allowed usage limits. In such case, see
this sample which saves cached results in a file.
You'll find the API playground where you can easily test any API function
here
Planyo can also inform your server whenever an event occurs, such as new reservation being entered or a reservation being cancelled etc. You don't need the API key for this functionality, please see
Q222 for the details.
The below limits are set by default. Please contact us if you need higher limits with a detailed explanation of your planned API usage.
The API should not receive simultaneous calls for a single API key. If this happens, the remaining calls will always wait for the original call to complete before being executed. You should therefore never do simultaneous calls, do only one at a time. If you do API calls triggered by user action (e.g. API call on your webpage), this can of course happen but will not cause any issues. The second (and third etc..) simultaneous call will simply get a 1-sec delay before being executed. Your calls will not fail due to this restriction.
We also use a rate limit throttling. In case of a heavy usage in a 10-second period, we'll add delays (1-4 seconds based on total running time in the previous 10 seconds). Also here your calls will not fail but will simply be delayed.
One reason your calls can fail with the error code 5 is if you exceed the usage limits:
- max 30 calls in 3 seconds
- max 300 calls in 1 minute
- max 3600 calls in 1 hour
- max 12000 calls in 1 day
API usage log & stats
