Catalog

Quick reference

API Type Latest version Test account Know how (s)
CatalogService SOAP and REST 1.33 available 

This service contains all methods used to access the content of the sellable catalog on a given point of sales.

This section is rich in object descriptions. Please refer to the glossary to get more details about a catalog's content.

It is important to cache the result of the calls on the caller side. See the FAQ below.

FAQ

How to proceed to a complete catalog export ?

Catalog export is done through methods getCatalog and getCatalogDetailed.

Recommandation: this method should be called once a day, OR when getLastSetupUpdate indicates that a modification did occur, remember call rate limitation explained in API Terms and Conditions.

How to detect changes in catalog ?

Method getLastSetupUpdate allows to know when the catalog has been updated the last time, to limit the number of full reloads.

How to find the point of sales id ?

Call method getPOSConfig. The pointOfSalesId is stored in POSConfigData.posId

How to the id of a product ?

Call getCatalogDetailed. Then find the product ids in catalogResult.catalogData.season.product.id.

What is the difference between getCatalog and getCatalogDetailed ?

Both methods return the full catalog. In one case as an XML string that has to be parsed by the client, in the other case as a full set of DTOs.

Why does getCatalogDetailed always timeout after 30s ?

The methods to retrieve the catalog do costly queries on the database as they retrieve the current status of the catalog. When their duration exceeds 30s, the result will contain the code in_progress. See S-360 webservices guidelines to understand how to handle this.

To avoid those lengthy calls, please use getLastSetupUpdate method.

Front-end handling of catalog data

Once the catalog data have been retrieved, front-end has some rules to apply to determine:

  • If the product is sellable
  • What is the price to apply.

Sellable products

The product can be sold if and only if:

  • The season is in state RUNNING
  • The product is in state RUNNING
  • The product or the performance have a Sales Period including "now"
  • The call to getProductAvailability/getEventAvaiilability/getPerformanceAvailability returns something else than NONE/SOLD_OUT/NOT_ON_SALE.

If a product cannot be sold now, its data can alaways be used to set up the point of sales.

Computing prices

The catalog can contain many prices for the same performance, audience sub category, with different price levels (optional). This case allows to propose different prices related to the contact executing the purchase.

Prices without price level, or linked to audience categories OCCASIONAL/INDIVIDUAL and INVITED/* are available for any contact, even anonymous ones.

If the contact is know, method getContactData must me called in order to retrieve the contact qualities listing the price levels to which the contact is entitled. Considering that, the price to display shoud be;

Anonymous price (linked to audience categories OCCASIONAL/INDIVIDUAL and INVITED/*)

Or, if the contact is a structure or a structure's relay, the prices linked to COMMUNITY/* audience categories can be also displayed.

In any case, display the lowest price for each audience category. It is advised to display this price with an explanation of the reason why it is lower.

If many season tickets are returned for the same audience sub category, it is not recommanded to display the different season tickets, but to regroup by audience sub category.

This situation is explained below:

Example :

  • Considering the price levels :

    • PLST1 : -30% for invidual subscribers « gold »
    • PLST2 : -10% for invidual subscribers « silver »
    • PLGR1 : -20% for group subscribers « children »
    • PLSC : -50% for group « VIP »

  • Considering a performance P1 with 4 public prices:

    • Cat1 / adult : 55€
    • Cat1 / child : 35€
    • Cat2 / adult : 50€
    • Cat2 / child : 30€

And the following prices:

  • Cat1 / adult / PLST1 : 39€

  • Cat1 / child / PLST1 : 25€

  • Cat1 / adult / PLST2 : 49€

  • Cat2 / adult / PLST2 : 45€

  • Cat2 / child / PLST2 : 27€

  • Cat1 / child / PLGR1 : 28€

  • Cat2 / child / PLGR1 : 24€

  • Cat1 / adult / PLSC : 27€

  • Cat1 / child / PLSC : 17€

  • Cat2 / adult / PLSC : 25€

  • Cat2 / child / PLSC : 15€

If a client having the price level PLGR1 is showing, 6 prices must be diplayed:

  • Cat1 / adult : 55€
  • Cat1 / child : 35€
  • Cat2 / adult : 50€
  • Cat2 / child : 30€
  • Cat1 / child / PLGR1 : 28€
  • Cat2 / child / PLGR1 : 24€

If a client having the price level PLST1 and PLGR1 is showing, 7 prices must be diplayed:

  • Cat1 / adult : 55€
  • Cat1 / child : 35€
  • Cat2 / adult : 50€
  • Cat2 / child : 30€
  • Cat1 / adult / PLST1 : 39€
  • Cat1 / child / PLST1 : 25€ (this price is lower than PLGR1)
  • Cat2 / child / PLGR1 : 24€

If a client having the price level  PLST2, PLGR1 & PLSC is showing, 12 prices must be diplayed:

  • Cat1 / adult : 55€

  • Cat1 / child : 35€

  • Cat2 / adult : 50€

  • Cat2 / child : 30€

  • Cat1 / adult / PLSC : 27€

  • Cat1 / child / PLSC : 17€

  • Cat2 / adult / PLSC : 25€

  • Cat2 / child / PLSC : 15€

  • Cat2 / adult / PLST2 : 45€

  • Cat2 / child / PLST2 : 27€

  • Cat1 / adult / PLST1 : 39€ (lower than the one of PLST2)

  • Cat1 / child / PLST1 : 25€

At last, if the contact is linked to a general public advantage, it is still possible to have another price list. It is again advised to display those prices in complement with the other prices, displaying a message showing that they come from the advantage.