Retrieving event dates and stock

Hi guys,

So I'm using the wonderful API to manage the booking process on my frontend. I have 3 different items, 2 are "regular items", and one is event based.

I have a dozen of events already planned in the future for my event based item, and I'd like to fetch them throught the API to display them in a table.

Right now, if I GET /item/:id with a timespan of one year, I get that kind of response:
"events": {
"3": {
"name": "Adventure 1"
"4": {
"name": "Adventure 2"
"6": {
"name": "Adventure 3"

I'd like to know if it's possible to get the dates along with the name of the event.

Moreover, I'm doing this for a client and I'm not yet very familiar with the administration. Is it possible to have an inventory per-event ? What I mean is, is it possible to have 10 items available for adventure 1, 3 items available for adventure 2, etc... ?

I saw in the admin that you could set it to "Available" or not, but nowhere can I specify the initial stock amount for that event...

Thanks a lot in advance !


  • edited December 2014
    At the moment, no, it's not possible for it to return the dates for the events as listed on the item directly, rather this array currently exists primarily to allow a summary title for applied events for the current selection. It's possible this could change in the future, but as an alternative that does return events and their dates, if you enable the "upcoming items" display under Manage > Layout > Booking Page, you can return the dates of all of your upcoming events by filtering the item call to your item (specifying 'item_id' as an argument) and attempting to query a date for which you're certain will never be available. This way, the API will return an "upcoming" object containing the dates of any events applicable to that item.

    The only way to have a variable stock for an event on different dates is to either allocate each event as a separate item (which could be aliased to a parent item to link stock, if your events ever need to overlap), or to manually alter the stock via the inventory calendar -- 'events' are dynamically applied (and can be combined with other events), rather than being the definition of a static inventory entry, so will not make authoritative changes to the items themselves. The latter calendar editing method is fairly simply to do through your Checkfront panel, and would keep a clean inventory; however, there are a few businesses that prefer to use the former model of having one-time events as individual items, and in some cases have delegated these to their own categories for quick access to the entire set via the API. This method does increase the apparent complexity significantly, and can be confusing when viewed in the calendars due to the number of items that can be involved, but on smaller inventories it is easy enough to set up.
    Personally, I prefer the method of using a single item, although I can see how being able to specify alterations in a more straightforward fashion would be useful.
  • Thank you very much Kris,

    I managed to get a list of all the upcoming events with ease, but now I'd like to display the inventory value for those specific timeframes. I could hit the API recursively to get the availability of each event by specifying the dates of the latter, but that means around 10 hits to the API at every page load, which isn't great for you or for me...

    FYI I also checked "Show number of items available to customers". Am I missing something ?

    Thanks again !
  • Because your events are on different dates, the only way to get the remaining stock for those dates is to query them; either individually, or as a full range encompassing them. The latter case can be heavy if you have high-frequency bookings, but in most cases should be reasonable. The fastest way to get nothing but the available count for an item is to call item/[item_id]/cal with a start_date and end_date defined, however, because this is currently primarily an internally used function for a datepicker calendar, it is limited to a 90 day range.

    For querying individual records, keep in mind that as communication occurs using the HTTP protocol, it is possible to keep the connection open with a Keep-Alive header to avoid the lookup, negotiation, and TLS handshake for additional requests. If you're using cURL, you'll want to make sure to retain the same connection handle to maintain this. While there is certainly a good deal of overhead included regardless, sequential requests from your application won't necessarily be overly slow -- and the cal call could be split into individual ranges to check the availability for those dates very quickly (additionally keep in mind that since any non-overlapping events would have the same stock across their range, you realistically only need to query a single date in their coverage area if all you're interested in is their count). If the communication between your server and you Checkfront account seems slow, it's also possible that there may be another node closer to where your server is hosted, and if you send an email to support, we can move your account as close as possible to the requesting server.

    In any case, regardless of how you would choose to query your available dates, there will be a bit of a delay if you're looking at a varied range of dates for that item. Perceptible, but not overwhelming. Personally, I would cache this data on your local server, which could be used virtually instantly without any communication delay. This cached data could update intermittently, expire after a validity period, or even use webhooks to invalidate only when a booking is created or changed. Because when booking an individual event date you will need to query them individually, the availability count cache can also be updated when creating a booking directly through your site, and should always have the correct count in the end as long as you're vigilant about keeping it updated transactionally.
This discussion has been closed.