Listings API

Design

The Listings API is designed for customers who wish to update the following details for a property specific to their Staylist

• state — enumerable string indicating whether this property is connected to your Staylist
• listing_url — URL string a property card goes to when clicked
• overview — text that appears on a property card
• featured — boolean value indicating whether a property is featured
• commission_override — decimal that overrides Staylist commission
• credit_cents — integer of credit (in lowest denomination of currency) applied to commission invoices
• credit_currency — string of three-letter ISO currency code

These values can be updated from your Staylist portal, but doing 1,000 listing URLS is probably faster programatically.

Request

As we are doing a partial update of existing data, make a PATCH request to the following endpoint, replacing {id} with the Staylist property ID you wish to update:

https://app.staylists.com/api/v3/listings/{id}

Parameters

state (optional)

The state of the listing. Set to "accepted" if you wish for the property to appear on your Staylist, or "declined" if it’s not right for you.

listing_url (optional)

The URL string of the property on your website. When a user clicks a property within an iframed collection, we’ll jump out of the iframe and take them to this URL. This means the user never leaves your site.

overview (optional)

This is the text that appears within a property card and is designed to be a short description or teaser for that property.

featured (optional)

Featured properties can be rendered as a separate collection, but as you’re probably building a website, you could do this quite easily within your own CMS. Nevertheless, there may be a use case for this in the future.

commission_override (optional)

If your Staylist charges, for example, a flat 10% commission on bookings, but you’ve negotiated a discounted rate for this particular property of, say, 8%, you can send us the integer 8 to override the commission for this given property. We also accepts decimals, so 3.14159 is ludicrous, but technically okay.

credit_cents and credit_currency (optional)

This is total amount of commission credit you wish to give this property. If you’d like to not charge any commission on this property’s first £2,500 of bookings, then you first need to ascertain their commission rate. If it’s 10%, then they’ll be getting £250 of credit against commission. Thus you’ll need to send us 25000 along with a credit_currency value of "GBP". This is because 25,000 pence is £250.

Authentication

This request requires authentication

Response

When a Listing is updated

{
    "object": "Listing",
    "data": {
        "name": "The Oak Tree Inn",
        "listing_url": "https://www.terrificplaces.com/inns/the-oak-tree",
        "overview": "Classic coaching inn nestled in the glorious Suffolk countryside serving home-cooked food through the day.",
        "featured": false,
        "credit_cents": 15000,
        "credit_currency": "GBP"
    }
}

When a Listing for the Property ID is not found

You’ll get an empty json body {} and a 404 response code.