MyTouristMyTourist API documentation Logging in

API documentation

REST API v1 https://app.mytourist.cloud/api/v1 JSON 57 endpoints
Contents

Getting started

The MyTourist REST API

Use the MyTourist API to integrate availability checks, bookings, debtors, invoices and a lot more into your website or app. MyTourist and your back-end communicate by sending HTTP requests back and forth.

The API implements a REST architecture. Sounds technical, but it is really quite easy: the HTTP methods GET, POST and DELETE match the operations to read, create or update, and delete. Every resource lives under one base URL, followed by the name of the resource you want to interact with.

We recommend reading these introduction topics entirely. If you have any questions about integrating our API, please contact us. We're happy to help!

Base URL
{BASE_URL}

Obtain an API token

The first thing you need is an API token. Each company profile has its own API token, shown on the API page in MyTourist (Connections → API). It is very important to keep your API token secure: never share it and never use it in front-end code. You can reset the token on the API page at any time; the old token stops working immediately.

Authentication

The API token must be sent with each API request in the Authorization header, using the Bearer method:

Authorization: Bearer {YOUR_API_TOKEN}

A request without a valid token returns HTTP 403 with the message Access denied, bearer token not found!. In the example on the right we use the API token to fetch the list of debtors.

Example request
curl -X GET '{BASE_URL}/debtors' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Requests and responses

  • Send parameters as form fields (multipart/form-data or application/x-www-form-urlencoded) or as a JSON body with the header Content-Type: application/json. Query parameters of GET requests go in the URL.
  • Every response is JSON, except the invoice PDF download.
  • Updates are partial: when you leave out a field, we keep the current value. When you send a field empty, it is cleared or reset to its default.
  • IDs are strings or numbers as shown in the examples. Always use the id from a response; never guess them.
  • The API is rate limited to 10 requests per 10 seconds. Above that, requests are refused with HTTP 429. Use the list endpoints with a date range instead of fetching items one by one.

Use at your own risk

No warranty: the API is provided as is. Test in a dummy company profile first.

We validate each request on basic rules, but via the API you operate outside the MyTourist interface and its checks. You are responsible for the data you add or change via the API. Each call is logged and kept for at least 24 months; you can see the most recent calls on the API page under "Recent API calls".

We strongly recommend testing your connection in a dummy company profile before you use it on your production profile. You can manage your company profiles in your account settings. If your connection causes data to become corrupt, we can charge you for restoring a backup of your company profile.

Start developing, test and deploy

Postman is a great tool for the first steps of building a connection. It lets you test all GET, POST and DELETE requests before you write any code. Leave the "Recent API calls" window on the API page open while you test: it refreshes every 10 seconds and shows each call with its result.

We sometimes host custom APIs on our infrastructure for customers and direct partners. Please contact us for more information.

HTTP responses

Every response comes with one of these HTTP status codes. On an error, the body contains a short message that tells you what went wrong.

CodeStatusMeaning
200 OK The request has been processed without any exceptions.
204 No content The calendar cache is being built. Try again in a moment.
400 Failed Not all required parameters are set, or the action is not allowed.
403 Forbidden The bearer token is missing or not valid.
404 Not found The URL is incorrect or the requested data no longer exists.
429 Too many requests More than 10 requests in 10 seconds. Wait a moment and try again.
500 Error The data you sent us could not be processed.
Common error messages
MessageWhen
Access denied, bearer token not found! The bearer token is missing or invalid.
Missing required field(s) Required parameters are missing.
Start-/end date are not set, or selected time period is longer than 36 days. Invoice or payment list without a valid date range.
Not possible to cancel bookings from external platforms. You tried to cancel a booking from a connected channel.
No rates are set for this roomtype The roomtype has no price rates, so the booking cannot be created.
Category locked You tried to change or delete the default product category.

Property

General address and company data of the company profile that belongs to the API token.

1 endpoints

Retrieve property data

GET /api/v1/property

Returns the address, contact and bank details of the company profile.

Fields in the response 20
  • unique string
    ID of the company profile.
  • name string
    Company name.
  • street string|null
    Street and house number.
  • zipcode string|null
  • city string|null
  • country string|null
    ISO 3166-1 alpha-2.
  • website string|null
  • email string|null
  • phone string|null
  • mobile string|null
  • currency string
    ISO 4217, for example EUR.
  • iban_name string|null
    Account holder.
  • iban string|null
  • bic string|null
  • iban_alt_name string|null
    Account holder of the second bank account.
  • iban_alt string|null
    Second bank account.
  • bic_alt string|null
  • company_id string|null
    Chamber of commerce number.
  • registration_id string|null
    VAT number.
  • custom_coordinates boolean|null
    The location on the map is set by hand.
Request
curl -X GET '{BASE_URL}/property' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
{
    "unique": "12410123",
    "name": "MyTourist BV",
    "street": "Meetkamp 4",
    "zipcode": "7078AJ",
    "city": "Megchelen",
    "country": "NL",
    "website": "mytourist.cloud",
    "email": "[email protected]",
    "phone": null,
    "mobile": "06xxxxxxxx",
    "currency": "EUR",
    "iban_name": "MyTourist",
    "iban": "NL00AAAA0123456",
    "bic": "NLMT01",
    "iban_alt_name": null,
    "iban_alt": null,
    "bic_alt": null,
    "company_id": "12345678",
    "registration_id": "987654321",
    "custom_coordinates": false
}

Bookings

Add and manage bookings. When you create a booking, MyTourist automatically creates the invoice and attaches the debtor. Bookings placed by other connected channels are partly locked.

11 endpoints

List bookings between dates

GET /api/v1/bookings

Returns all bookings in the period for each roomtype in your account. To prevent heavy requests you need to give a from and until date; these may not be more than 36 days apart.

Query parameters
  • from date required
    Format YYYY-MM-DD.
  • until date required
    Format YYYY-MM-DD.
  • roomtype_id string
    Only return bookings of this roomtype.
  • show_cancellations boolean
    Also return cancelled bookings.
Fields in the response 34
  • id integer
    Booking ID. Use it for the other booking endpoints.
  • website_order_id string|null
    Order ID when the booking was made in the booking engine.
  • state string
    optional, confirmed or cancelled.
  • arrival date
    YYYY-MM-DD.
  • departure date
    YYYY-MM-DD.
  • expected_arrival_time time|null
    HH:MM:SS.
  • auto_send_email boolean
    The guest receives the automatic emails.
  • roomtype.id string
    ID of the roomtype.
  • roomtype.name string
  • roomtype.placed_in_room string|null
    Name of the room the booking is placed in.
  • debtor_id string|null
    ID of the debtor.
  • debtor object
    The debtor, in the same format as Retrieve a debtor (without bookings and invoices).
  • number_of_guests integer
  • guests[] array
    Details per guest: salutation, firstname, lastname, birthday, address, zipcode, city, country, phone, email.
  • dietary_wishes string|null
  • access_code string|null
    Access code of the room or building.
  • note string|null
    Internal note.
  • commission_amount float|null
    Commission of the channel.
  • rate.id string
    ID of the price rate.
  • rate.name string
  • channel.id string
    ID of the channel.
  • channel.label string
    For example mytourist, website, api or booking.com.
  • channel.reference string|null
    Reference of the booking at the channel.
  • channel.info string|null
  • forced_logies_price float|false
    Forced logies price, or false when the price is calculated.
  • invoice_enabled boolean
    An invoice is made for this booking.
  • invoice object
    Main invoice: id, total_amount_incl_vat, total_amount_excl_vat, has_amount_to_pay. See Invoices.
  • breakfast_booked boolean
  • related_bookings[] array
    Bookings made together: id and is_main_booking.
  • mybooking_url string|null
    Link to the booking page for the guest.
  • created_at datetime
    YYYY-MM-DD HH:MM:SS.
  • updated_at datetime
    YYYY-MM-DD HH:MM:SS.
  • checkin_at datetime|null
    Moment of check-in.
  • checkout_at datetime|null
    Moment of check-out.
Request
curl -G '{BASE_URL}/bookings' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --data-urlencode 'from=2030-07-01' \
  --data-urlencode 'until=2030-07-31'
Response · 200
[
    {
        "id": 231920102956,
        "website_order_id": null,
        "state": "confirmed",
        "arrival": "2023-10-08",
        "departure": "2023-10-11",
        "expected_arrival_time": "19:00:00",
        "auto_send_email": true,
        "roomtype": {
            "id": "23192010281",
            "name": "Doubleroom with balcony",
            "placed_in_room": "Room 1"
        },
        "debtor_id": "23192010294",
        "debtor": {
            "id": "23192010294",
            "company_name": null,
            "company_chamber_id": null,
            "first_name": "Max",
            "last_name": "Musterman",
            "address": "Streetname 55 Block 3",
            "...": "..."
        },
        "number_of_guests": 2,
        "guests": [
            {
                "salutation": "male",
                "firstname": "Max",
                "lastname": "Musterman",
                "birthday": "1985-04-01",
                "address": "Demostreet 44",
                "zipcode": "123456",
                "city": "Amsterlin",
                "country": "NL",
                "phone": "0031 0800 0101",
                "email": "[email protected]"
            },
            {
                "salutation": "female",
                "firstname": "Maxine",
                "...": "..."
            }
        ],
        "dietary_wishes": "No gluten",
        "access_code": "1234",
        "note": "Brings bicycles and would like to park them in the garage",
        "commission_amount": null,
        "rate": {
            "id": "23192010281",
            "name": "Default price rate"
        },
        "channel": {
            "id": "115TALSTRIPADVISORC1603970714",
            "label": "tripadvisor",
            "reference": "[email protected]",
            "info": "Booking imported from tripadvisor"
        },
        "forced_logies_price": 300.00,
        "invoice_enabled": true,
        "invoice": {
            "id": "P102006",
            "total_amount_incl_vat": 300,
            "total_amount_excl_vat": 240,
            "has_amount_to_pay": true
        },
        "breakfast_booked": true,
        "related_bookings": [
            { "id": 1210531312, "is_main_booking": true },
            { "id": 1210531313, "is_main_booking": false }
        ],
        "mybooking_url": "https://app.mytourist.cloud/mybooking/231920102956/...",
        "created_at": "2023-09-29 12:25:16",
        "updated_at": "2023-09-29 12:25:16",
        "checkin_at": "2023-10-08 14:35:51",
        "checkout_at": null
    },
    { "...": "..." }
]

List bookings of a debtor

GET /api/v1/bookings/from-debtor

Like List bookings between dates, but for all bookings of one debtor.

Query parameters
  • debtor_id string required
    ID of the debtor.
  • show_cancellations boolean
    Also return cancelled bookings.
Response

Same format as List bookings between dates.

Request
curl -G '{BASE_URL}/bookings/from-debtor' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --data-urlencode 'debtor_id=23192010294'

List bookings currently staying

GET /api/v1/bookings/current-bookings

Returns all bookings that arrive, stay or depart on the given date (default today). Like the insights page in MyTourist, the bookings are sorted by the order of the rooms and roomtypes.

Query parameters
  • date date
    Format YYYYMMDD. Empty is today.
  • light boolean
    Faster response with less data. Default false.
Request
curl -G '{BASE_URL}/bookings/current-bookings' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --data-urlencode 'date=20300701' \
  --data-urlencode 'light=true'

Retrieve a booking

GET /api/v1/bookings/{BOOKING_ID}

Returns one booking with all information.

Fields in the response 34
  • id integer
    Booking ID. Use it for the other booking endpoints.
  • website_order_id string|null
    Order ID when the booking was made in the booking engine.
  • state string
    optional, confirmed or cancelled.
  • arrival date
    YYYY-MM-DD.
  • departure date
    YYYY-MM-DD.
  • expected_arrival_time time|null
    HH:MM:SS.
  • auto_send_email boolean
    The guest receives the automatic emails.
  • roomtype.id string
    ID of the roomtype.
  • roomtype.name string
  • roomtype.placed_in_room string|null
    Name of the room the booking is placed in.
  • debtor_id string|null
    ID of the debtor.
  • debtor object
    The debtor, in the same format as Retrieve a debtor (without bookings and invoices).
  • number_of_guests integer
  • guests[] array
    Details per guest: salutation, firstname, lastname, birthday, address, zipcode, city, country, phone, email.
  • dietary_wishes string|null
  • access_code string|null
    Access code of the room or building.
  • note string|null
    Internal note.
  • commission_amount float|null
    Commission of the channel.
  • rate.id string
    ID of the price rate.
  • rate.name string
  • channel.id string
    ID of the channel.
  • channel.label string
    For example mytourist, website, api or booking.com.
  • channel.reference string|null
    Reference of the booking at the channel.
  • channel.info string|null
  • forced_logies_price float|false
    Forced logies price, or false when the price is calculated.
  • invoice_enabled boolean
    An invoice is made for this booking.
  • invoice object
    Main invoice: id, total_amount_incl_vat, total_amount_excl_vat, has_amount_to_pay. See Invoices.
  • breakfast_booked boolean
  • related_bookings[] array
    Bookings made together: id and is_main_booking.
  • mybooking_url string|null
    Link to the booking page for the guest.
  • created_at datetime
    YYYY-MM-DD HH:MM:SS.
  • updated_at datetime
    YYYY-MM-DD HH:MM:SS.
  • checkin_at datetime|null
    Moment of check-in.
  • checkout_at datetime|null
    Moment of check-out.
Request
curl -X GET '{BASE_URL}/bookings/{BOOKING_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
{
    "id": 231920102956,
    "website_order_id": null,
    "state": "confirmed",
    "arrival": "2023-10-08",
    "departure": "2023-10-11",
    "expected_arrival_time": "19:00:00",
    "auto_send_email": true,
    "roomtype": {
        "id": "23192010281",
        "name": "Doubleroom with balcony",
        "placed_in_room": "Room 1"
    },
    "debtor_id": "23192010294",
    "debtor": {
        "id": "23192010294",
        "company_name": null,
        "company_chamber_id": null,
        "first_name": "Max",
        "last_name": "Musterman",
        "address": "Streetname 55 Block 3",
        "...": "..."
    },
    "number_of_guests": 2,
    "guests": [
        {
            "salutation": "male",
            "firstname": "Max",
            "lastname": "Musterman",
            "birthday": "1985-04-01",
            "address": "Demostreet 44",
            "zipcode": "123456",
            "city": "Amsterlin",
            "country": "NL",
            "phone": "0031 0800 0101",
            "email": "[email protected]"
        },
        {
            "salutation": "female",
            "firstname": "Maxine",
            "...": "..."
        }
    ],
    "dietary_wishes": "No gluten",
    "access_code": "1234",
    "note": "Brings bicycles and would like to park them in the garage",
    "commission_amount": null,
    "rate": {
        "id": "23192010281",
        "name": "Default price rate"
    },
    "channel": {
        "id": "115TALSTRIPADVISORC1603970714",
        "label": "tripadvisor",
        "reference": "[email protected]",
        "info": "Booking imported from tripadvisor"
    },
    "forced_logies_price": 300.00,
    "invoice_enabled": true,
    "invoice": {
        "id": "P102006",
        "total_amount_incl_vat": 300,
        "total_amount_excl_vat": 240,
        "has_amount_to_pay": true
    },
    "breakfast_booked": true,
    "related_bookings": [
        { "id": 1210531312, "is_main_booking": true },
        { "id": 1210531313, "is_main_booking": false }
    ],
    "mybooking_url": "https://app.mytourist.cloud/mybooking/231920102956/...",
    "created_at": "2023-09-29 12:25:16",
    "updated_at": "2023-09-29 12:25:16",
    "checkin_at": "2023-10-08 14:35:51",
    "checkout_at": null
}

Create a booking

POST /api/v1/bookings

The price rate_id must belong to the roomtype_id.

This endpoint expects that you have already checked the availability. It validates the availability of the roomtype once more, but checking it first with the availability endpoint is faster.

Parameters
  • channel string
    Default mytourist. See available channels.
  • arrival date required
    Format YYYY-MM-DD.
  • departure date required
    Format YYYY-MM-DD.
  • roomtype_id string required
    ID of a roomtype.
  • rate_id string
    ID of a price rate of the selected roomtype. Default: the first rate of the roomtype.
  • unit_id string
    Preferred room. When this room is not available, MyTourist picks another available room.
  • debtor_id string
    ID of a debtor. Default: no debtor attached.
  • number_of_guests integer
    Default 1.
  • number_of_children integer
    Default 0.
  • state string
    optional or confirmed (default).
  • auto_send_email boolean
    Send the automatic emails to the guest. Default true.
  • channel_reference string
    Your own reference of the booking, for example the order number on your platform.
  • dietary_wishes string
  • access_code string
  • note string
    Internal note.
  • commission_amount float
  • forced_logies_price float
    Force the logies price on the invoice.
  • expected_arrival_time string
    Per quarter of an hour from 10.00 up to 23.45, or 23.59.
  • invoice_enabled boolean
    Only on create. Create an invoice for this booking. Default true.
  • checkin_at datetime
    Format YYYY-MM-DD HH:MM:SS.
  • checkout_at datetime
    Format YYYY-MM-DD HH:MM:SS.
Response

Returns the created booking, in the same format as Retrieve a booking.

Request
curl -X POST '{BASE_URL}/bookings' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'channel=api' \
  --form 'arrival=2030-07-01' \
  --form 'departure=2030-07-04' \
  --form 'roomtype_id=23192010281' \
  --form 'rate_id=23192010281' \
  --form 'debtor_id=23192010294' \
  --form 'number_of_guests=2'

Update a booking

POST /api/v1/bookings/{BOOKING_ID}

Send the changed JSON or only the fields you want to change. A field you leave out is ignored; a field you send empty is reset to its default or null.

  • Bookings from connected channels are partly locked for synchronization: arrival, departure, channel and channel_reference are not accepted.
  • When you change the roomtype, change the price rate as well. Without a rate_id we take the default price rate of the new roomtype.
Parameters
  • channel string
    Default mytourist. See available channels.
  • arrival date
    Format YYYY-MM-DD.
  • departure date
    Format YYYY-MM-DD.
  • roomtype_id string
    ID of a roomtype.
  • rate_id string
    ID of a price rate of the selected roomtype. Default: the first rate of the roomtype.
  • unit_id string
    Preferred room. When this room is not available, MyTourist picks another available room.
  • debtor_id string
    ID of a debtor. Default: no debtor attached.
  • number_of_guests integer
    Default 1.
  • number_of_children integer
    Default 0.
  • state string
    optional or confirmed (default).
  • auto_send_email boolean
    Send the automatic emails to the guest. Default true.
  • channel_reference string
    Your own reference of the booking, for example the order number on your platform.
  • dietary_wishes string
  • access_code string
  • note string
    Internal note.
  • commission_amount float
  • forced_logies_price float
    Force the logies price on the invoice.
  • expected_arrival_time string
    Per quarter of an hour from 10.00 up to 23.45, or 23.59.
  • invoice_enabled boolean
    Only on create. Create an invoice for this booking. Default true.
  • checkin_at datetime
    Format YYYY-MM-DD HH:MM:SS.
  • checkout_at datetime
    Format YYYY-MM-DD HH:MM:SS.
  • recalculate_invoice_logies boolean
    Send true to recalculate the logies lines on the invoice.
Response

Returns the updated booking.

Request
curl -X POST '{BASE_URL}/bookings/{BOOKING_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'number_of_guests=3' \
  --form 'recalculate_invoice_logies=true'

Cancel a booking

DELETE /api/v1/bookings/{BOOKING_ID}

Only bookings from mytourist, website (booking engine) or api can be cancelled via the API. Bookings with a live connection to an external platform cannot be cancelled here. If a booking is out of sync, please contact support.

Request
curl -X DELETE '{BASE_URL}/bookings/{BOOKING_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Attach to a booking

POST /api/v1/bookings/{BOOKING_ID}/attach

Attach this booking to a main booking. MyTourist then merges both invoices. Only bookings from mytourist, website or api can be attached.

Parameters
  • main_reservation integer required
    ID of the main booking.
Request
curl -X POST '{BASE_URL}/bookings/{BOOKING_ID}/attach' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'main_reservation=1210531312'

Detach from a booking

POST /api/v1/bookings/{BOOKING_ID}/detach

Detach this booking from its main booking. MyTourist creates a new invoice for the detached booking. Only bookings from mytourist, website or api can be detached.

Request
curl -X POST '{BASE_URL}/bookings/{BOOKING_ID}/detach' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

List guests

GET /api/v1/bookings/{BOOKING_ID}/guests

Returns all guests of one booking.

Request
curl -X GET '{BASE_URL}/bookings/{BOOKING_ID}/guests' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
[
    {
        "guest_id": 1,
        "salutation": "male",
        "firstname": "Max",
        "lastname": "Musterman",
        "birthday": "1962-07-03",
        "address": "Previewstreet 44",
        "zipcode": "1234AA",
        "city": "Amsterdam",
        "country": "NL",
        "phone": "06123456789",
        "email": "[email protected]"
    },
    { "guest_id": 2, "...": "..." }
]

Update a guest

POST /api/v1/bookings/{BOOKING_ID}/guests/{GUEST_ID}

Update one guest of a booking. Use the guest_id from List guests.

Parameters
  • salutation string
    male or female.
  • firstname string
  • lastname string
  • birthday date
    Format YYYYMMDD.
  • address string
  • zipcode string
  • city string
  • country string
    ISO 3166-1 alpha-2, for example NL.
  • phone string
  • email string
Request
curl -X POST '{BASE_URL}/bookings/{BOOKING_ID}/guests/{GUEST_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'firstname=Max' \
  --form 'lastname=Musterman'

Available channels

ChannelMeaning
mytourist Creates the booking as if it was created in the MyTourist interface.
api Creates the booking as an external channel. The booking is locked in MyTourist and can only be changed via the API.

Availability

Check which roomtypes are available in a date range, with the calculated total logies price per price rate. With this result you have enough data to create a booking.

1 endpoints

Check availability

GET /api/v1/availability

This endpoint returns cached results. The cache refreshes after a change in your account; it can take a few minutes before the change is visible.

Checks the availability of one or all roomtypes in a date range. The API always returns the number of available rooms per roomtype, some information about the roomtype (so you need fewer calls to the roomtypes endpoint) and its price rates.

Need the availability and price per day, for example for a calendar? Use Fetch the calendar data instead.

Query parameters
  • arrival date required
    Format YYYY-MM-DD.
  • departure date required
    Format YYYY-MM-DD.
  • roomtype_id string
    Only return this roomtype.
  • language string
    ISO 639-1, for example en.
Reasons a rate is not available
ReasonMeaning
closedonarrival Arrival is not possible for this rate on this day.
closedondeparture Departure is not possible for this rate on this day.
minstay The number of nights is less than the minimum stay.
maxstay The number of nights is more than the maximum stay.
Fields in the response 9
  • id string
    ID of the roomtype.
  • rooms_available integer
    Live number of available rooms in this roomtype.
  • name string
    Name of the roomtype.
  • description string
  • rates[].id integer
    ID of the price rate. Use it as rate_id to create a booking.
  • rates[].rate_available boolean
    The rate can be booked for this stay.
  • rates[].total_price float
    Total logies price for the stay, without bookable extras. 0 when not available.
  • rates[].name string
  • rates[].reasons array
    Why the rate is not available; empty when it is. See the table.
Request
curl -G '{BASE_URL}/availability' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --data-urlencode 'arrival=2030-07-01' \
  --data-urlencode 'departure=2030-07-04'
Response · 200
[
    {
        "id": "81912063",
        "rooms_available": 1,
        "name": "Doubleroom Deluxe with balcony",
        "description": "Our best room with an amazing view over the city!",
        "rates": [
            {
                "id": 66118004,
                "rate_available": true,
                "total_price": 200,
                "name": "Conform arrangement",
                "reasons": []
            },
            {
                "id": 82010274,
                "rate_available": false,
                "total_price": 0,
                "name": "Bubbles arrangement - Long weekend",
                "reasons": ["closedonarrival", "minstay"]
            }
        ]
    }
]

Calendar

The MyTourist calendar is the central place where it all comes together: bookings, price rates, available rooms and restrictions like minimum and maximum stay and closed for arrival or departure.

3 endpoints

Fetch the calendar data

POST /api/v1/calendar

This endpoint returns cached results. The cache refreshes after a change in your account; it can take a few minutes. While the cache is being built, you get HTTP 204: try again shortly.

Returns the number of available rooms and the current logies price per price rate for each day of the month of the given date. You can fetch all roomtypes or a single one.

Parameters
  • date date required
    Format YYYY-MM-DD. The month of this date is returned.
  • roomtype_id string
    Only return this roomtype.
  • language string
    ISO 639-1, for example en.
Response

The result is grouped by roomtype ID, then by date (YYYYMMDD), then by price rate ID.

Fields in the response 14
  • {roomtype_id}.{date} object
    One day of one roomtype. The date is YYYYMMDD.
  • availability.value integer
    Rooms to sell on this day.
  • availability.custom_value boolean
    The number was changed by hand (bulk change) instead of the default.
  • prices.{rate_id}.min_stay integer|null
    Minimum number of nights.
  • prices.{rate_id}.max_stay integer|null
    Maximum number of nights.
  • prices.{rate_id}.closed_on_arrival boolean
    No arrival possible on this day.
  • prices.{rate_id}.closed_on_departure boolean
    No departure possible on this day.
  • prices.{rate_id}.name string
    Internal name of the rate.
  • prices.{rate_id}.public_name string
    Name in the booking engine, in the requested language.
  • prices.{rate_id}.current_price float
    Price per night on this day.
  • prices.{rate_id}.default_price float
    Default price per night of the rate.
  • prices.{rate_id}.is_custom_price boolean
    The price was changed for this day.
  • prices.{rate_id}.is_subrate boolean
    Only for sub rates: the price follows another rate.
  • prices.{rate_id}.subrate object
    adjusted_by (percentage or amount) and value.
Request
curl -X POST '{BASE_URL}/calendar' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'date=2030-07-01'
Response · 200
{
    "4719120611": {
        "20301130": {
            "availability": {
                "value": 2,
                "custom_value": false
            },
            "prices": {
                "120022112": {
                    "id": "120022112",
                    "min_stay": 2,
                    "max_stay": 3,
                    "closed_on_arrival": false,
                    "closed_on_departure": true,
                    "name": "Weekend arrangement",
                    "public_name": "Stay with 15% discount - from 3 nights",
                    "current_price": 100,
                    "default_price": 100,
                    "is_custom_price": false
                },
                "120022113": {
                    "id": "120022113",
                    "min_stay": 3,
                    "max_stay": 14,
                    "closed_on_arrival": false,
                    "closed_on_departure": true,
                    "name": "OTA (booking.com)",
                    "public_name": "",
                    "current_price": 110,
                    "default_price": 110,
                    "is_custom_price": false,
                    "is_subrate": true,
                    "subrate": {
                        "adjusted_by": "percentage",
                        "value": "10"
                    }
                }
            }
        },
        "20301201": { "...": "..." }
    }
}

Bulk changes

POST /api/v1/calendar/{RATE_ID}

Change the availability, price and restrictions of one price rate for one day or a period. With this endpoint you no longer need to make bulk changes in the MyTourist calendar by hand. The until date may be at most 2 years ahead.

Parameters
  • from date required
    Format YYYY-MM-DD.
  • until date required
    Format YYYY-MM-DD.
  • rooms_to_sell integer
    Rooms to sell; never higher than the actual number of rooms. Bookings are subtracted automatically. Use auto for the default.
  • min_stay integer
    Nights, or auto for the default of the price rate.
  • max_stay integer
    Nights, or auto for the default of the price rate.
  • close_to_arrival string
    closed or open, or default to reset to the price rate settings.
  • close_to_departure string
    closed or open, or default to reset to the price rate settings.
  • price_per_night decimal
    Price per night, or auto for the default price.
Request
curl -X POST '{BASE_URL}/calendar/{RATE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'from=2030-01-01' \
  --form 'until=2030-01-01' \
  --form 'rooms_to_sell=1'

Change availability for one day

Lower the number of available rooms to 1.

Example
curl -X POST '{BASE_URL}/calendar/{RATE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'from=2030-01-01' \
  --form 'until=2030-01-01' \
  --form 'rooms_to_sell=1'

Close a period for arrival

No arrivals possible in this period; departures stay open.

Example
curl -X POST '{BASE_URL}/calendar/{RATE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'from=2030-01-01' \
  --form 'until=2030-05-15' \
  --form 'close_to_arrival=closed' \
  --form 'close_to_departure=open'

Change the price for one week

Set the price per night to 100.

Example
curl -X POST '{BASE_URL}/calendar/{RATE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'from=2030-01-01' \
  --form 'until=2030-01-07' \
  --form 'price_per_night=100.00'

Reset everything to the defaults

Take the default availability, price and restrictions of the price rate.

Example
curl -X POST '{BASE_URL}/calendar/{RATE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'from=2030-01-01' \
  --form 'until=2030-01-07' \
  --form 'rooms_to_sell=auto' \
  --form 'price_per_night=auto' \
  --form 'min_stay=auto' \
  --form 'max_stay=auto' \
  --form 'close_to_arrival=default' \
  --form 'close_to_departure=default'

Multiple bulk changes in one request

POST /api/v1/calendar/bulk

Post a JSON array to push several bulk changes in one call. Each item takes the same fields as Bulk changes, plus the rate_id.

Request
curl -X POST '{BASE_URL}/calendar/bulk' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  -H 'Content-Type: application/json' \
  --data-raw '[
    {
        "rate_id": "12345678",
        "from": "2030-08-14",
        "until": "2030-08-14",
        "price_per_night": "55",
        "min_stay": 3
    },
    {
        "rate_id": "87654321",
        "from": "2030-08-15",
        "until": "2030-08-17",
        "price_per_night": "60",
        "min_stay": 2
    }
]'
JSON body
[
    {
        "rate_id": "12345678",
        "from": "2030-08-14",
        "until": "2030-08-14",
        "price_per_night": "55",
        "min_stay": 3
    },
    {
        "rate_id": "87654321",
        "from": "2030-08-15",
        "until": "2030-08-17",
        "price_per_night": "60",
        "min_stay": 2
    }
]

Debtors

Manage your debtors: the guests and companies that book and pay.

6 endpoints

List all debtors

GET /api/v1/debtors

Returns all your debtors, newest first.

Fields in the response 17
  • id string
    Debtor ID. Use it for the other debtor endpoints and as debtor_id in bookings and invoices.
  • company_name string|null
  • company_chamber_id string|null
    Chamber of commerce number (KVK).
  • first_name string
  • last_name string
  • address string|null
    Street and house number.
  • zipcode string|null
  • city string|null
  • country string|null
    ISO 3166-1 alpha-2.
  • email string|null
  • mobile string|null
  • phone string|null
  • vat_id string|null
    VAT number.
  • note string|null
  • bank_account string|null
  • latitude string|null
  • longitude string|null
Request
curl -X GET '{BASE_URL}/debtors' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
[
    {
        "id": "23192010299",
        "company_name": null,
        "company_chamber_id": null,
        "first_name": "Max",
        "last_name": "Musterman",
        "address": "Streetname 55 Block 3",
        "zipcode": "1234AB",
        "city": "Amsterdam",
        "country": "NL",
        "email": "[email protected]",
        "mobile": "0612345678",
        "phone": null,
        "vat_id": null,
        "note": null,
        "bank_account": null,
        "latitude": "27.606888",
        "longitude": "-42.670898"
    },
    { "...": "..." }
]

Retrieve a debtor

GET /api/v1/debtors/{DEBTOR_ID}

Returns one debtor, including all bookings and invoices of this debtor.

Fields in the response 19
  • id string
    Debtor ID. Use it for the other debtor endpoints and as debtor_id in bookings and invoices.
  • company_name string|null
  • company_chamber_id string|null
    Chamber of commerce number (KVK).
  • first_name string
  • last_name string
  • address string|null
    Street and house number.
  • zipcode string|null
  • city string|null
  • country string|null
    ISO 3166-1 alpha-2.
  • email string|null
  • mobile string|null
  • phone string|null
  • vat_id string|null
    VAT number.
  • note string|null
  • bank_account string|null
  • latitude string|null
  • longitude string|null
  • bookings[] array
    Bookings of this debtor: id, state, arrival, departure.
  • invoices[] array
    Invoices of this debtor: id, state, type.
Request
curl -X GET '{BASE_URL}/debtors/{DEBTOR_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
{
    "id": "23192010299",
    "company_name": null,
    "company_chamber_id": null,
    "first_name": "Max",
    "last_name": "Musterman",
    "address": "Streetname 55 Block 3",
    "zipcode": "1234AB",
    "city": "Amsterdam",
    "country": "NL",
    "email": "[email protected]",
    "mobile": "0612345678",
    "phone": null,
    "vat_id": null,
    "note": null,
    "bank_account": null,
    "latitude": "27.606888",
    "longitude": "-42.670898",
    "bookings": [
        {
            "id": 231920102956,
            "state": "archived",
            "arrival": "20201008",
            "departure": "20201011"
        }
    ],
    "invoices": [
        {
            "id": "P1120078",
            "state": "open",
            "type": "proforma"
        }
    ]
}

Create a debtor

POST /api/v1/debtors

Creates a debtor and returns it.

Parameters
  • first_name string required
  • last_name string required
  • company_name string
  • company_chamber_id string
    Chamber of commerce number (KVK).
  • vat_id string
  • bank_account string
  • address string
  • zipcode string
  • city string
  • country string
    ISO 3166-1 alpha-2, for example NL.
  • mobile string
  • phone string
  • email string
  • note string
  • latitude float
    For example 27.606888.
  • longitude float
    For example -42.670898.
Response

Returns the saved debtor, in the same format as Retrieve a debtor.

Request
curl -X POST '{BASE_URL}/debtors' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'first_name=Max' \
  --form 'last_name=Musterman' \
  --form '[email protected]'

Update a debtor

POST /api/v1/debtors/{DEBTOR_ID}

Send the full JSON or only the fields you want to change. A field you send is always overwritten; a field you leave out keeps its current value.

Parameters
  • first_name string
  • last_name string
  • company_name string
  • company_chamber_id string
    Chamber of commerce number (KVK).
  • vat_id string
  • bank_account string
  • address string
  • zipcode string
  • city string
  • country string
    ISO 3166-1 alpha-2, for example NL.
  • mobile string
  • phone string
  • email string
  • note string
  • latitude float
    For example 27.606888.
  • longitude float
    For example -42.670898.
Response

Returns the saved debtor.

Request
curl -X POST '{BASE_URL}/debtors/{DEBTOR_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form '[email protected]' \
  --form 'mobile=0612345678'

Delete a debtor

DELETE /api/v1/debtors/{DEBTOR_ID}

Deletes the debtor. Returns success, or HTTP 400 when the debtor does not exist.

Request
curl -X DELETE '{BASE_URL}/debtors/{DEBTOR_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Invoices

By default, MyTourist creates an invoice for each booking and calculates the logies price, tourist tax and fixed products. You can also create single invoices without a booking, for example for boat or bike rentals, a bar or activities. With these endpoints you manage invoices, product lines and payments.

14 endpoints

List invoices

GET /api/v1/invoices

Returns all invoices with an invoice date in the period. To prevent heavy server load, from and until are required and may be at most 36 days apart.

Query parameters
  • from date required
    Format YYYY-MM-DD.
  • until date required
    Format YYYY-MM-DD.
Fields in the response 30
  • id string
    Invoice ID, for example P1020077. Use it for the other invoice endpoints.
  • invoiced_at string
    Invoice date, YYYYMMDD.
  • invoice_id string|null
    Invoice number from your administration; null while the invoice is a proforma.
  • language string
    Language of the invoice.
  • type string
    proforma, invoice or creditinvoice. See the table.
  • reservation string|null
    ID of the booking, or null for a single invoice.
  • financial_state string
    concept, open, payed or credited. See the table.
  • debtor_id string|null
    ID of the debtor.
  • footnote string
    Text at the bottom of the invoice.
  • reference string|null
    Reference of the customer, for example an order or PO number.
  • product_lines[].id string
    Line ID. Use it to update or remove the line.
  • product_lines[].type string
    logies or product.
  • product_lines[].number number
    Number of items.
  • product_lines[].description string
  • product_lines[].price_incl_vat string
    Total of the line incl. VAT.
  • product_lines[].price_excl_vat string
    Total of the line excl. VAT.
  • product_lines[].tax_amount string
    VAT amount of the line.
  • product_lines[].tax_rate string|null
    VAT percentage.
  • product_lines[].tax_type string|null
    Type of the tax rate: standard, zero (0% VAT) or exempt (no VAT: exempt or outside the scope of VAT, tax_rate is then 0). null when the line has no tax rate or was created before this field existed.
  • product_lines[].product_id string|null
    ID of the product, or null for a line added by hand.
  • tourist_tax object
    Only for booking invoices: amount, based_on_guests and outdated.
  • vat_lines object
    VAT amount per rate: { "21": 12.50 }. Lines without VAT (tax_type exempt) are under the key exempt, always with amount 0: { "21": 12.50, "exempt": 0 }.
  • payments[] array
    Payments: id, payment_method, amount, description, created_at.
  • financial.has_amount_to_pay boolean
    Something is still open to pay.
  • financial.custom_logies_price boolean
    The logies price is forced on the booking.
  • financial.deposit_amount string
    Deposit to pay.
  • financial.deposit_open_to_pay float
    Part of the deposit that is still open.
  • financial.total_amount_incl_vat float
  • financial.total_amount_excl_vat float
  • financial.total_paid float
    Total of all payments.
Request
curl -G '{BASE_URL}/invoices' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --data-urlencode 'from=2030-11-01' \
  --data-urlencode 'until=2030-11-30'
Response · 200
[
    {
        "id": "P1020077",
        "invoiced_at": "20301104",
        "invoice_id": null,
        "language": "en",
        "type": "proforma",
        "reservation": "1240815785",
        "financial_state": "open",
        "debtor_id": "23192010282",
        "footnote": "",
        "reference": "PO-12345",
        "product_lines": [
            {
                "id": "2319201102165",
                "type": "logies",
                "number": 1,
                "description": "Doubleroom with balcony - 7 night(s) - 2 guest(s)",
                "price_incl_vat": "560.00",
                "price_excl_vat": "504.50",
                "tax_amount": "55.50",
                "tax_rate": "11.00",
                "tax_type": "standard",
                "product_id": null
            },
            {
                "id": "2319201102164",
                "type": "product",
                "number": 8,
                "description": "Bottle of red wine",
                "price_incl_vat": "352.00",
                "price_excl_vat": "317.12",
                "tax_amount": "34.88",
                "tax_rate": "11.00",
                "tax_type": "standard",
                "product_id": null
            }
        ],
        "tourist_tax": {
            "amount": "0.00",
            "based_on_guests": 0,
            "outdated": false
        },
        "vat_lines": {
            "11": 90.38
        },
        "payments": [
            {
                "id": "23192011021",
                "payment_method": "bank_card",
                "amount": "10.00",
                "description": "",
                "created_at": "2030-11-04 10:12:00"
            }
        ],
        "financial": {
            "has_amount_to_pay": true,
            "custom_logies_price": false,
            "deposit_amount": "112.00",
            "deposit_open_to_pay": 102,
            "total_amount_incl_vat": 912,
            "total_amount_excl_vat": 821.62,
            "total_paid": 10
        }
    }
]

Retrieve an invoice

GET /api/v1/invoices/{INVOICE_ID}

Returns one invoice. Use the id of the invoice (for example P1020077).

Types
TypeMeaning
proforma Not final yet. You can still change the invoice and it can be removed completely.
invoice Final: internally marked as sent to the customer, and always registered in your administration.
creditinvoice A credit invoice, linked to the invoice it credits.
Financial states
StateMeaning
concept The proforma invoice has not been sent yet, so the amount to pay is still a concept.
open The invoice has been sent to the guest and is waiting for payment.
payed The invoice has been paid in full.
credited The amount to pay has been credited with a credit invoice.
Product line types
TypeMeaning
logies Calculated automatically by MyTourist. To force this amount, set forced_logies_price on the booking.
product A product from MyTourist or a line added by hand.
Fields in the response 30
  • id string
    Invoice ID, for example P1020077. Use it for the other invoice endpoints.
  • invoiced_at string
    Invoice date, YYYYMMDD.
  • invoice_id string|null
    Invoice number from your administration; null while the invoice is a proforma.
  • language string
    Language of the invoice.
  • type string
    proforma, invoice or creditinvoice. See the table.
  • reservation string|null
    ID of the booking, or null for a single invoice.
  • financial_state string
    concept, open, payed or credited. See the table.
  • debtor_id string|null
    ID of the debtor.
  • footnote string
    Text at the bottom of the invoice.
  • reference string|null
    Reference of the customer, for example an order or PO number.
  • product_lines[].id string
    Line ID. Use it to update or remove the line.
  • product_lines[].type string
    logies or product.
  • product_lines[].number number
    Number of items.
  • product_lines[].description string
  • product_lines[].price_incl_vat string
    Total of the line incl. VAT.
  • product_lines[].price_excl_vat string
    Total of the line excl. VAT.
  • product_lines[].tax_amount string
    VAT amount of the line.
  • product_lines[].tax_rate string|null
    VAT percentage.
  • product_lines[].tax_type string|null
    Type of the tax rate: standard, zero (0% VAT) or exempt (no VAT: exempt or outside the scope of VAT, tax_rate is then 0). null when the line has no tax rate or was created before this field existed.
  • product_lines[].product_id string|null
    ID of the product, or null for a line added by hand.
  • tourist_tax object
    Only for booking invoices: amount, based_on_guests and outdated.
  • vat_lines object
    VAT amount per rate: { "21": 12.50 }. Lines without VAT (tax_type exempt) are under the key exempt, always with amount 0: { "21": 12.50, "exempt": 0 }.
  • payments[] array
    Payments: id, payment_method, amount, description, created_at.
  • financial.has_amount_to_pay boolean
    Something is still open to pay.
  • financial.custom_logies_price boolean
    The logies price is forced on the booking.
  • financial.deposit_amount string
    Deposit to pay.
  • financial.deposit_open_to_pay float
    Part of the deposit that is still open.
  • financial.total_amount_incl_vat float
  • financial.total_amount_excl_vat float
  • financial.total_paid float
    Total of all payments.
Request
curl -X GET '{BASE_URL}/invoices/{INVOICE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
{
    "id": "P1020077",
    "invoiced_at": "20301104",
    "invoice_id": null,
    "language": "en",
    "type": "proforma",
    "reservation": "1240815785",
    "financial_state": "open",
    "debtor_id": "23192010282",
    "footnote": "",
    "reference": "PO-12345",
    "product_lines": [
        {
            "id": "2319201102165",
            "type": "logies",
            "number": 1,
            "description": "Doubleroom with balcony - 7 night(s) - 2 guest(s)",
            "price_incl_vat": "560.00",
            "price_excl_vat": "504.50",
            "tax_amount": "55.50",
            "tax_rate": "11.00",
            "tax_type": "standard",
            "product_id": null
        },
        {
            "id": "2319201102164",
            "type": "product",
            "number": 8,
            "description": "Bottle of red wine",
            "price_incl_vat": "352.00",
            "price_excl_vat": "317.12",
            "tax_amount": "34.88",
            "tax_rate": "11.00",
            "tax_type": "standard",
            "product_id": null
        }
    ],
    "tourist_tax": {
        "amount": "0.00",
        "based_on_guests": 0,
        "outdated": false
    },
    "vat_lines": {
        "11": 90.38
    },
    "payments": [
        {
            "id": "23192011021",
            "payment_method": "bank_card",
            "amount": "10.00",
            "description": "",
            "created_at": "2030-11-04 10:12:00"
        }
    ],
    "financial": {
        "has_amount_to_pay": true,
        "custom_logies_price": false,
        "deposit_amount": "112.00",
        "deposit_open_to_pay": 102,
        "total_amount_incl_vat": 912,
        "total_amount_excl_vat": 821.62,
        "total_paid": 10
    }
}

Create an invoice

POST /api/v1/invoices

Creates a single invoice without a booking. It works exactly like a booking invoice, except that the automatic price calculation (price rates and tourist tax) is not active. A new invoice is always a proforma.

Parameters
  • debtor_id string
    ID of a debtor.
  • lang string
    nl, de, en or fr. Default: the invoice language of your account.
  • invoiced_at date
    Format YYYYMMDD. Is set again when you make the invoice final.
  • footnote string
    Default: the footnote of your account.
  • reference string
    Reference (for example the order or PO number of the customer), shown on the invoice. Max. 255 characters; send it empty to clear it.
Response

Returns the created invoice, in the same format as Retrieve an invoice.

Request
curl -X POST '{BASE_URL}/invoices' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'debtor_id=23192010282' \
  --form 'reference=PO-12345'

Update an invoice

POST /api/v1/invoices/{INVOICE_ID}

Changes only the fields you send.

Parameters
  • debtor_id string
    ID of a debtor.
  • lang string
    nl, de, en or fr. Default: the invoice language of your account.
  • invoiced_at date
    Format YYYYMMDD. Is set again when you make the invoice final.
  • footnote string
    Default: the footnote of your account.
  • reference string
    Reference (for example the order or PO number of the customer), shown on the invoice. Max. 255 characters; send it empty to clear it.
Response

Returns the updated invoice.

Request
curl -X POST '{BASE_URL}/invoices/{INVOICE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'reference=PO-12345' \
  --form 'footnote=Thank you for your stay!'

Make an invoice final

POST /api/v1/invoices/make-final/{INVOICE_ID}

Gives the proforma invoice the next invoice number from your administration and changes its type to invoice. A final invoice can no longer be removed; it can only be credited.

Parameters
  • invoice_date date
    Format YYYY-MM-DD. Default: today.
Response

Returns the final invoice.

Request
curl -X POST '{BASE_URL}/invoices/make-final/{INVOICE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Credit an invoice

POST /api/v1/invoices/{INVOICE_ID}/credit

Creates a credit invoice for a final invoice: a copy with the same lines, all with negative amounts. This is the same as the button "Credit" in MyTourist. The credit invoice starts as a proforma, so you can still check it; make it final with its id. Only final invoices can be credited (HTTP 400 for a proforma).

Response

Returns the new credit invoice, in the same format as Retrieve an invoice.

Request
curl -X POST '{BASE_URL}/invoices/{INVOICE_ID}/credit' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Delete a proforma invoice

DELETE /api/v1/invoices/{INVOICE_ID}

Removes a proforma invoice. Final invoices cannot be removed (HTTP 400).

Request
curl -X DELETE '{BASE_URL}/invoices/{INVOICE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Add a product line

POST /api/v1/invoices/{INVOICE_ID}/lines

Add a product from MyTourist, or your own line with a description and price. When you add the same product again, its number is increased.

Parameters
  • number integer required
    Number of items.
  • description string required
    Is replaced by the product name when you send a product_id.
  • price_incl float
    Price per item incl. VAT. Needed when you do not send a product_id.
  • product_id string
    ID of a product. The product name and tax rate are used.
  • tax_id string
    ID of a tax rate. Only without a product_id.
  • information string
    Extra information on the line.
Fields in the response 12
  • id string
    Line ID.
  • type string
    logies or product.
  • number number
    Number of items.
  • description string
  • total_price_incl_vat float
    Total of the line incl. VAT.
  • total_price_excl_vat float
    Total of the line excl. VAT.
  • piece_price_incl_vat float
    Price per item incl. VAT.
  • piece_price_excl_vat float
    Price per item excl. VAT.
  • tax_amount float
    VAT amount of the line.
  • tax_rate float|null
    VAT percentage.
  • tax_type string|null
    standard, zero or exempt (no VAT). See tax rates.
  • product_id string|null
    ID of the product, or null for a line added by hand.
Request
curl -X POST '{BASE_URL}/invoices/{INVOICE_ID}/lines' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'number=2' \
  --form 'description=Bike rental' \
  --form 'price_incl=14.00'
Response · 200
{
    "id": "2319201102164",
    "type": "product",
    "number": 8,
    "description": "Bottle of red wine",
    "total_price_incl_vat": 352,
    "total_price_excl_vat": 317.12,
    "piece_price_incl_vat": 44,
    "piece_price_excl_vat": 39.64,
    "tax_amount": 34.88,
    "tax_rate": 11,
    "tax_type": "standard",
    "product_id": null
}

Update a product line

POST /api/v1/invoices/{INVOICE_ID}/lines/{LINE_ID}

Changes only the fields you send.

Parameters
  • number integer
    Number of items.
  • description string
  • price_incl float
    Price per item incl. VAT.
  • product_id string
    ID of a product.
  • tax_id string
    ID of a tax rate.
Fields in the response 12
  • id string
    Line ID.
  • type string
    logies or product.
  • number number
    Number of items.
  • description string
  • total_price_incl_vat float
    Total of the line incl. VAT.
  • total_price_excl_vat float
    Total of the line excl. VAT.
  • piece_price_incl_vat float
    Price per item incl. VAT.
  • piece_price_excl_vat float
    Price per item excl. VAT.
  • tax_amount float
    VAT amount of the line.
  • tax_rate float|null
    VAT percentage.
  • tax_type string|null
    standard, zero or exempt (no VAT). See tax rates.
  • product_id string|null
    ID of the product, or null for a line added by hand.
Request
curl -X POST '{BASE_URL}/invoices/{INVOICE_ID}/lines/{LINE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'number=3'
Response · 200
{
    "id": "2319201102164",
    "type": "product",
    "number": 8,
    "description": "Bottle of red wine",
    "total_price_incl_vat": 352,
    "total_price_excl_vat": 317.12,
    "piece_price_incl_vat": 44,
    "piece_price_excl_vat": 39.64,
    "tax_amount": 34.88,
    "tax_rate": 11,
    "tax_type": "standard",
    "product_id": null
}

Remove a product line

DELETE /api/v1/invoices/{INVOICE_ID}/lines/{LINE_ID}

Removes the line and returns it.

Request
curl -X DELETE '{BASE_URL}/invoices/{INVOICE_ID}/lines/{LINE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

List all payments

GET /api/v1/invoices/payments

Returns all payments in the period, of all invoices. from and until may be at most 36 days apart.

Query parameters
  • from date required
    Format YYYY-MM-DD.
  • until date required
    Format YYYY-MM-DD.
Request
curl -G '{BASE_URL}/invoices/payments' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --data-urlencode 'from=2030-11-01' \
  --data-urlencode 'until=2030-11-30'
Response · 200
[
    {
        "id": "23192011021",
        "invoice": "F2030-0012",
        "payment_method": "bank_card",
        "amount": "10.00",
        "description": "",
        "created_at": "2030-11-04 10:12:00"
    }
]

Add a payment

POST /api/v1/invoices/{INVOICE_ID}/payments

Registers a payment on the invoice. We do not send the guest a notification for payments you add via the API.

Parameters
  • payment_type string required
    bank_transfer, bank_card, credit_card, cash, voucher, channel, cheque or provider.
  • amount float required
    For a refund, send a negative amount.
  • description string
Fields in the response 4
  • id string
    Payment ID. Use it to remove the payment.
  • payment_method string
    See the parameter payment_type.
  • amount float
    Negative for a refund.
  • description string|null
Request
curl -X POST '{BASE_URL}/invoices/{INVOICE_ID}/payments' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'payment_type=bank_card' \
  --form 'amount=10.00'
Response · 200
{
    "id": "23192011021",
    "payment_method": "bank_card",
    "amount": 10,
    "description": "Paid at the reception"
}

Remove a payment

DELETE /api/v1/invoices/{INVOICE_ID}/payments/{PAYMENT_ID}

Removes the payment and returns it.

Request
curl -X DELETE '{BASE_URL}/invoices/{INVOICE_ID}/payments/{PAYMENT_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
{
    "id": "23192011021",
    "payment_method": "bank_card",
    "amount": 10,
    "description": "Paid at the reception"
}

Download an invoice

GET /api/v1/invoices/{INVOICE_ID}/pdf

Returns the invoice as PDF (application/pdf). The authorization header is still required.

Request
curl -X GET '{BASE_URL}/invoices/{INVOICE_ID}/pdf' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Roomtypes

Roomtypes are groups of rooms, like "Doubleroom" with "Room 6, 1st floor" and "Room 4, 3rd floor". A B&B often has one room per roomtype, with the same name. Roomtypes and rooms are managed in MyTourist; via the API you can read them.

1 endpoints

List all roomtypes

GET /api/v1/roomtypes

Returns all roomtypes with their rooms, pictures and price rates.

Query parameters
  • language string
    ISO 639-1, for example en.
Fields in the response 12
  • id string
    Roomtype ID. Use it as roomtype_id in other endpoints.
  • type string
    Kind of roomtype, for example double.
  • number_of_rooms integer
  • name string
    Internal name.
  • square_meters integer|null
  • amenities array
    Codes of the amenities, for example safe or hair_dryer.
  • public_names object
    Name in the booking engine per language.
  • public_descriptions object
    Description per language.
  • default_picture string|null
    URL of the main picture.
  • pictures array
    URLs of all pictures.
  • rooms[] array
    Rooms: id (use it as unit_id in bookings) and name.
  • rates[] array
    Price rates: id, name and public_names.
Request
curl -X GET '{BASE_URL}/roomtypes' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
[
    {
        "id": "81912063",
        "type": "double",
        "number_of_rooms": 3,
        "name": "Doubleroom Deluxe with balcony",
        "square_meters": 20,
        "amenities": ["safe", "sofa", "hair_dryer", "seating_area"],
        "public_names": {
            "nl": "Luxe tweepersoonskamer",
            "en": "Luxury double room",
            "de": "..."
        },
        "public_descriptions": {
            "nl": "Deze kamer is van alle luxe voorzien!",
            "en": "This room is equipped with every luxury!",
            "de": "..."
        },
        "default_picture": "https://cdn.mytourist.cloud/rooms/medium/21MTYZ....jpg",
        "pictures": [
            "https://cdn.mytourist.cloud/rooms/medium/21MTWN....jpg",
            "https://cdn.mytourist.cloud/rooms/medium/21MTYZ....jpg"
        ],
        "rooms": [
            { "id": "66118888", "name": "Room 1" },
            { "id": "66118777", "name": "Room 4" },
            { "id": "66118666", "name": "Room 8" }
        ],
        "rates": [
            {
                "id": "66118004",
                "name": "Conform arrangement",
                "public_names": {
                    "nl": "Standaardprijs 2 personen",
                    "en": "Standard price 2 persons"
                }
            }
        ]
    }
]

Price rates

Each roomtype has its own price rates. You can have as many as you want, for example weekend arrangements or long and short stay rates. Price rates can be connected to channels like Booking.com.

2 endpoints

List all price rates

GET /api/v1/price-rates

Returns the price rates of one roomtype, or of all roomtypes.

Query parameters
  • roomtype_id string
    Recommended. Only return the price rates of this roomtype.
  • language string
    ISO 639-1, for example en.
Fields explained
FieldMeaning
parent_id Set when the rate is a sub rate of another rate (cleaner calendar, price can follow the parent in percentages).
public_name When the rate is visible in the booking engine, your name is translated automatically into about 15 languages.
enabled_for_booking_engine The rate is bookable in your booking engine.
min_advance / max_advance Number of hours before arrival.
closed_on_arrival Weekdays without arrival: mo,tu,we,th,fr,sa,su.
closed_on_departure Weekdays without departure: mo,tu,we,th,fr,sa,su.
default_price_per_night Default price per night, in your currency or as a percentage.
price_per_night_percentage The price is a percentage of the parent rate (only for sub rates).
Request
curl -G '{BASE_URL}/price-rates' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --data-urlencode 'roomtype_id=23192010281'
Response · 200
[
    {
        "id": "23192010281",
        "default_price_per_night": "70.00",
        "price_per_night_percentage": false,
        "...": "..."
    },
    {
        "id": "23192011041",
        "parent_id": "23192010281",
        "roomtype_id": "23192010281",
        "internal_name": "Long weekend",
        "public_name": {
            "nl": "Lang weekend",
            "de": "Verlängertes Wochenende"
        },
        "note": "Only bookable in the weekends. Based on the main price with -10%",
        "enabled_for_booking_engine": true,
        "persons": 2,
        "min_stay": 4,
        "max_stay": null,
        "min_advance": 24,
        "max_advance": 24,
        "closed_on_arrival": "mo,tu,we,th,sa,su",
        "closed_on_departure": "tu,we,th,fr,sa",
        "default_price_per_night": "10.00",
        "price_per_night_percentage": true,
        "created_at": "2030-11-04 12:21:29",
        "updated_at": "2030-11-04 12:21:29"
    }
]

Retrieve a price rate

GET /api/v1/price-rates/{RATE_ID}

Returns one price rate, in the same format as the list. The same query parameters can be used.

Request
curl -X GET '{BASE_URL}/price-rates/{RATE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Tax rates

Manage your VAT rates: a label, the rate itself and its type. Tax rates rarely change, but you can manage them via the API.

4 endpoints

List all tax rates

GET /api/v1/tax-rates

Returns all your tax rates.

Fields in the response 7
  • id string
    Tax rate ID. Use it as tax_id in products and invoice lines.
  • label string
  • rate float
    Percentage. Always 0 for the types zero and exempt.
  • type string
    standard (a percentage), zero (a real 0% VAT rate) or exempt (no VAT: exempt or outside the scope of VAT). See the table.
  • invoice_note string|null
    Text shown on invoices and quotations that use this rate, for example the legal ground for the exemption.
  • created_at datetime
    ISO 8601.
  • updated_at datetime
    ISO 8601.
Request
curl -X GET '{BASE_URL}/tax-rates' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
[
    {
        "id": "23192011033",
        "label": "Low",
        "rate": 9,
        "type": "standard",
        "invoice_note": null,
        "created_at": "2030-11-03T09:52:42.000000Z",
        "updated_at": "2030-11-03T09:52:42.000000Z"
    },
    {
        "id": "23192011034",
        "label": "High",
        "rate": 21,
        "type": "standard",
        "invoice_note": null,
        "created_at": "2030-11-03T09:52:46.000000Z",
        "updated_at": "2030-11-03T09:52:46.000000Z"
    }
]

Create a tax rate

POST /api/v1/tax-rates

Creates a tax rate and returns it.

Parameters
  • label string required
  • rate float required
    Percentage. Ignored (set to 0) for the types zero and exempt.
  • type string
    standard (default), zero or exempt. See the table.
  • invoice_note string
    Text on the invoice, max. 500 characters. For example Exempt from VAT under article 11.
Types
TypeMeaningOn the invoice
standard A VAT percentage, for example 9 or 21. 21%
zero A real 0% VAT rate: the revenue is taxed, at 0%. 0%
exempt No VAT: the revenue is exempt or outside the scope of VAT. For your accounting this is not the same as 0%. No VAT, in the language of the invoice
Request
curl -X POST '{BASE_URL}/tax-rates' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'label=High' \
  --form 'rate=21' \
  --form 'type=standard'
Response · 200
{
    "id": "23192011034",
    "label": "High",
    "rate": 21,
    "type": "standard",
    "invoice_note": null,
    "created_at": "2030-11-03T09:52:46.000000Z",
    "updated_at": "2030-11-03T09:52:46.000000Z"
}

A rate without VAT

For revenue that is exempt from VAT. Invoices show *No VAT* instead of *0%*, with your text below the VAT summary.

Example
curl -X POST '{BASE_URL}/tax-rates' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'label=Exempt' \
  --form 'rate=0' \
  --form 'type=exempt' \
  --form 'invoice_note=Exempt from VAT under article 11'

Update a tax rate

POST /api/v1/tax-rates/{RATE_ID}

Final invoices keep the rate and type they were made with. Proforma invoices follow the change when you save the rate in the app with Apply to all proforma invoices.

Changes the fields you send and returns the tax rate.

Parameters
  • label string
  • rate float
    Percentage. Ignored (set to 0) for the types zero and exempt.
  • type string
    standard, zero or exempt.
  • invoice_note string
    Text on the invoice. Send an empty value to remove it.
Request
curl -X POST '{BASE_URL}/tax-rates/{RATE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'rate=21'
Response · 200
{
    "id": "23192011034",
    "label": "High",
    "rate": 21,
    "type": "standard",
    "invoice_note": null,
    "created_at": "2030-11-03T09:52:46.000000Z",
    "updated_at": "2030-11-03T09:52:46.000000Z"
}

Delete a tax rate

DELETE /api/v1/tax-rates/{RATE_ID}

Check your products and invoice lines before you delete a tax rate.

Invoice lines can still refer to this rate. Existing invoices keep their calculated amounts, but when you change such a line later, no tax is calculated anymore.

Request
curl -X DELETE '{BASE_URL}/tax-rates/{RATE_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Products

Products can be added to invoices, or offered as extras in your booking engine. You can also add a product to each booking automatically, for example final cleaning, and calculate the price per guest and/or per night.

5 endpoints

List all products

GET /api/v1/products

Returns all your products.

Fields in the response 9
  • id string
    Product ID. Use it as product_id in invoice lines.
  • category object
    The product category: id, name, color.
  • tax_id string|null
    ID of the tax rate.
  • language string
    Language of name and description.
  • price float
    Price per piece incl. VAT.
  • name string
  • description string
  • translations object
    Automatic translations of name and description per language.
  • calculation_methods array
    person and/or night: the price is multiplied by the number of guests and/or nights.
Request
curl -X GET '{BASE_URL}/products' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
[
    {
        "id": "23192011031",
        "category": {
            "id": "23192010291",
            "name": "Rental",
            "color": "#55BB5A"
        },
        "tax_id": "23192011034",
        "language": "en",
        "price": 14.00,
        "name": "Bike rental",
        "description": "Electric bike.",
        "translations": {
            "name": { "de": "Fahrradverleih", "...": "..." },
            "description": { "de": "Elektrisches Fahrrad", "...": "..." }
        },
        "calculation_methods": ["person", "night"]
    },
    { "...": "..." }
]

Retrieve a product

GET /api/v1/products/{PRODUCT_ID}

Returns one product.

Fields in the response 9
  • id string
    Product ID. Use it as product_id in invoice lines.
  • category object
    The product category: id, name, color.
  • tax_id string|null
    ID of the tax rate.
  • language string
    Language of name and description.
  • price float
    Price per piece incl. VAT.
  • name string
  • description string
  • translations object
    Automatic translations of name and description per language.
  • calculation_methods array
    person and/or night: the price is multiplied by the number of guests and/or nights.
Request
curl -X GET '{BASE_URL}/products/{PRODUCT_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
{
    "id": "23192011031",
    "category": {
        "id": "23192010291",
        "name": "Rental",
        "color": "#55BB5A"
    },
    "tax_id": "23192011034",
    "language": "en",
    "price": 14.00,
    "name": "Bike rental",
    "description": "Electric bike.",
    "translations": {
        "name": { "de": "Fahrradverleih", "...": "..." },
        "description": { "de": "Elektrisches Fahrrad", "...": "..." }
    },
    "calculation_methods": ["person", "night"]
}

Create a product

POST /api/v1/products

We advise to write name and description in the language of your invoices, so your invoices do not show an automatic translation. Translations of name and description are made automatically 30 minutes after your last change.

Parameters
  • language string required
    nl, de, fr or en: the language of name and description.
  • name string required
    In the language you set.
  • description string required
    In the language you set.
  • price float required
    Price per piece.
  • category_id string
  • tax_id string
    ID of a tax rate.
  • calculation_methods string
    person and/or night, separated by a comma. The price is then multiplied by the number of guests and/or nights.
  • auto_add_when_booked_on_roomtypes string
    IDs of roomtypes, separated by commas. The product is added to every booking of these roomtypes, for example final cleaning.
Response

Returns the created product.

Request
curl -X POST '{BASE_URL}/products' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'language=en' \
  --form 'name=Bike rental' \
  --form 'description=Electric bike.' \
  --form 'price=14.00'

Update a product

POST /api/v1/products/{PRODUCT_ID}

The same as creating, but no field is required. Only the fields you send are changed (also empty ones).

Parameters
  • language string
    nl, de, fr or en: the language of name and description.
  • name string
    In the language you set.
  • description string
    In the language you set.
  • price float
    Price per piece.
  • category_id string
  • tax_id string
    ID of a tax rate.
  • calculation_methods string
    person and/or night, separated by a comma. The price is then multiplied by the number of guests and/or nights.
  • auto_add_when_booked_on_roomtypes string
    IDs of roomtypes, separated by commas. The product is added to every booking of these roomtypes, for example final cleaning.
Response

Returns the updated product.

Request
curl -X POST '{BASE_URL}/products/{PRODUCT_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'price=15.00'

Remove a product

DELETE /api/v1/products/{PRODUCT_ID}

Proforma invoices are not changed. To remove the product from those invoices too, remove the product lines.

Request
curl -X DELETE '{BASE_URL}/products/{PRODUCT_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Product categories

Keep a clear overview of your products with categories. A category has a name and a color, and is only visible to you, not to your guests.

4 endpoints

List all product categories

GET /api/v1/product-categories

The first item is always the default category, marked as locked. You cannot change it; all other categories are free to change.

Fields in the response 6
  • id string
    Category ID. Use it as category_id in products.
  • name string|null
    null for the default category.
  • color string
    HEX color without #.
  • locked boolean
    The default category; it cannot be changed or removed.
  • created_at datetime
  • updated_at datetime
Request
curl -X GET '{BASE_URL}/product-categories' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
[
    {
        "id": "23192010291",
        "name": null,
        "color": "55BB5A",
        "locked": true,
        "created_at": "2030-10-29 13:58:07",
        "updated_at": "2030-10-29 13:58:07"
    },
    {
        "id": "23192011032",
        "name": "Bike rental",
        "color": "e44a7c",
        "locked": false,
        "created_at": "2030-11-03 15:11:41",
        "updated_at": "2030-11-03 15:11:41"
    }
]

Create a product category

POST /api/v1/product-categories

Creates a category and returns it.

Parameters
  • name string required
    For internal use only.
  • color string
    HEX color, for example e44a7c.
Request
curl -X POST '{BASE_URL}/product-categories' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'name=Bike rental' \
  --form 'color=e44a7c'

Update a product category

POST /api/v1/product-categories/{CATEGORY_ID}

Changes the fields you send. The locked default category cannot be changed (Category locked).

Parameters
  • name string
  • color string
    HEX color.
Request
curl -X POST '{BASE_URL}/product-categories/{CATEGORY_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'name=Bikes'

Remove a product category

DELETE /api/v1/product-categories/{CATEGORY_ID}

All products in this category move to the locked default category.

Request
curl -X DELETE '{BASE_URL}/product-categories/{CATEGORY_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Vouchers

Guests can use vouchers and discount codes to book with a discount in the booking engine. With these endpoints you create, change and delete them.

5 endpoints

List all vouchers

GET /api/v1/vouchers

Returns all available vouchers and discount codes.

Fields in the response 13
  • id string
    Voucher ID. Use it for the other voucher endpoints.
  • code string
    The code the guest enters.
  • type string
    discount or voucher.
  • is_percentage boolean
    amount is a percentage.
  • amount string
    Amount or percentage.
  • label string|null
  • description string|null
  • expires_at datetime|null
    ISO 8601.
  • language string|null
    Only for type voucher.
  • limit_date_from datetime|null
    Only for type discount: valid for stays from this date.
  • limit_date_until datetime|null
    Only for type discount: valid for stays until this date.
  • times_to_use integer|null
    Only for type discount: how often the code can be used.
  • excluded_rates array
    IDs of price rates the code does not apply to. Empty: valid for all rates.
Request
curl -X GET '{BASE_URL}/vouchers' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
[
    {
        "id": "04250025",
        "code": "4863-6862",
        "type": "discount",
        "is_percentage": false,
        "amount": "50.00",
        "label": "Spring",
        "description": "Example discount",
        "expires_at": "2030-04-19T22:00:00.000000Z",
        "language": "en",
        "limit_date_from": "2030-03-31T22:00:00.000000Z",
        "limit_date_until": "2030-04-09T22:00:00.000000Z",
        "times_to_use": 3,
        "excluded_rates": []
    },
    { "...": "..." }
]

Retrieve a voucher

GET /api/v1/vouchers/{VOUCHER_ID}

Returns one voucher.

Fields in the response 13
  • id string
    Voucher ID. Use it for the other voucher endpoints.
  • code string
    The code the guest enters.
  • type string
    discount or voucher.
  • is_percentage boolean
    amount is a percentage.
  • amount string
    Amount or percentage.
  • label string|null
  • description string|null
  • expires_at datetime|null
    ISO 8601.
  • language string|null
    Only for type voucher.
  • limit_date_from datetime|null
    Only for type discount: valid for stays from this date.
  • limit_date_until datetime|null
    Only for type discount: valid for stays until this date.
  • times_to_use integer|null
    Only for type discount: how often the code can be used.
  • excluded_rates array
    IDs of price rates the code does not apply to. Empty: valid for all rates.
Request
curl -X GET '{BASE_URL}/vouchers/{VOUCHER_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'
Response · 200
{
    "id": "04250025",
    "code": "4863-6862",
    "type": "discount",
    "is_percentage": false,
    "amount": "50.00",
    "label": "Spring",
    "description": "Example discount",
    "expires_at": "2030-04-19T22:00:00.000000Z",
    "language": "en",
    "limit_date_from": "2030-03-31T22:00:00.000000Z",
    "limit_date_until": "2030-04-09T22:00:00.000000Z",
    "times_to_use": 3,
    "excluded_rates": []
}

Create a voucher

POST /api/v1/vouchers

Creates a voucher or discount code and returns it.

Parameters
  • amount float required
    Amount, or percentage when is_percentage is true.
  • code string
    Discount code. Generated automatically when empty.
  • type string
    discount (default) or voucher.
  • is_percentage boolean
    Default false.
  • label string
  • description string
  • expires_at datetime
    Format YYYY-MM-DD HH:MM:SS.
  • language string
    ISO 639-1. Only for type voucher.
  • limit_date_from date
    Format YYYY-MM-DD. Only for type discount.
  • limit_date_until date
    Format YYYY-MM-DD. Only for type discount.
  • times_to_use integer
    Only for type discount.
  • excluded_rates string
    IDs of price rates the code does not apply to, separated by commas. Default: valid for all rates. Send it empty to clear it.
Request
curl -X POST '{BASE_URL}/vouchers' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'amount=50.00' \
  --form 'type=discount'
Response · 200
{
    "id": "04250025",
    "code": "4863-6862",
    "type": "discount",
    "is_percentage": false,
    "amount": "50.00",
    "label": "Spring",
    "description": "Example discount",
    "expires_at": "2030-04-19T22:00:00.000000Z",
    "language": "en",
    "limit_date_from": "2030-03-31T22:00:00.000000Z",
    "limit_date_until": "2030-04-09T22:00:00.000000Z",
    "times_to_use": 3,
    "excluded_rates": []
}

Update a voucher

POST /api/v1/vouchers/{VOUCHER_ID}

Send the full JSON or only the fields you want to change. A field you send is always overwritten; a field you leave out keeps its current value.

Parameters
  • amount float
    Amount, or percentage when is_percentage is true.
  • code string
    Discount code. Generated automatically when empty.
  • type string
    discount (default) or voucher.
  • is_percentage boolean
    Default false.
  • label string
  • description string
  • expires_at datetime
    Format YYYY-MM-DD HH:MM:SS.
  • language string
    ISO 639-1. Only for type voucher.
  • limit_date_from date
    Format YYYY-MM-DD. Only for type discount.
  • limit_date_until date
    Format YYYY-MM-DD. Only for type discount.
  • times_to_use integer
    Only for type discount.
  • excluded_rates string
    IDs of price rates the code does not apply to, separated by commas. Default: valid for all rates. Send it empty to clear it.
Request
curl -X POST '{BASE_URL}/vouchers/{VOUCHER_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}' \
  --form 'times_to_use=5'
Response · 200
{
    "id": "04250025",
    "code": "4863-6862",
    "type": "discount",
    "is_percentage": false,
    "amount": "50.00",
    "label": "Spring",
    "description": "Example discount",
    "expires_at": "2030-04-19T22:00:00.000000Z",
    "language": "en",
    "limit_date_from": "2030-03-31T22:00:00.000000Z",
    "limit_date_until": "2030-04-09T22:00:00.000000Z",
    "times_to_use": 3,
    "excluded_rates": []
}

Delete a voucher

DELETE /api/v1/vouchers/{VOUCHER_ID}

Deletes the voucher or discount code.

Request
curl -X DELETE '{BASE_URL}/vouchers/{VOUCHER_ID}' \
  -H 'Authorization: Bearer {YOUR_API_TOKEN}'

Webhooks

Get a message from MyTourist as soon as something happens with a booking, instead of asking the API again and again.

Set up webhooks

You find the webhooks page under Connections → Webhooks. Add a URL (starting with https://, max. 250 characters) and choose when it is called. As soon as that happens, we send a POST request to your URL.

The body contains the field trigger plus all booking data, in the same format as Retrieve a booking.

To test your webhooks, we recommend webhook.site.

Triggers
TriggerWhen
booking_created A booking has been created.
booking_updated A booking has been changed.
booking_cancelled A booking has been cancelled.
booking_checkin A guest has checked in.
booking_checkout A guest has checked out.
Webhook body
{
    "trigger": "booking_created",
    "id": 231920102956,
    "state": "confirmed",
    "arrival": "2030-10-08",
    "departure": "2030-10-11",
    "...": "..."
}

Delivery and retries

Reply with HTTP 200 to confirm that you received the webhook. Any other response, or no response, counts as failed. A failed webhook is sent again after 5, 15 and 60 minutes. After the third retry we stop.

No webhooks are sent for "out of order" blocks.