Endpoints : Product management#

The following sections will describe each endpoints providing at least one example.

Create a product#

Path

POST /api/supplier/{supplierId}/product

Input parameters

Table 6 - Description of the input parameters in the “Create a product” endpoint#

Field

Mandatory

Type

Description

Example

supplierId

Y

integer

Identifier of the supplier which provides the product

8214

externalId

Y

string[255]

Identifier of the supplier

f27a4b3d-24c4

title

Y

JSON object

Name of the product per language

 {“de”: “Kayak Paddle”, “en”: “”, “es”: “Kayak Paddle”, “fr”: “Kayak Paddle”}

countryCode

N

string[2]

Iso 3166-alpha2 country code

FR

zipCode

N

string[20]

Zip code

75011

rating

N

float

Feed the rating average (range is [0-5])

3.8

numberOfRatings

N

integer

Feed the rating count

3276

cityName

N

string[255]

City name

Paris

id

N/A

integer

autogenerated

0

creationDate

N/A

date

autogenerated

2022-03-29T09:10:30.931Z

channel

N

string[32]

Identifies the channel through which the supplier uploads the content for our application

ALENTOUR

internalName

N

string[255]

Supplier name

Kayak-Evasion

reference

N

string[255]

Same as externalId

LR1-01

instantConfirmation

N

boolean

Instant confirmation boolean

true

instantDelivery

N

boolean

Instant delivery boolean

true

availabilityType

N

string[255]

Describes how availability is designed for this product

[ START_TIME, OPENING_HOURS ]

redemptionMethod

N

string[255]

Information about redemption methods available for this product

[ MANIFEST, DIGITAL, PRINT ]

subtitle

N

JSON object

Subtitle of the product

{“de”: “Kayak Paddle”, “en”: “ Stand up paddle in the Mediterean Sea “, “es”: “Kayak Paddle en el Mar Mediteraneo”, “fr”: “Kayak Paddle”}

shortDescription

N

JSON object

Short description/presentation of the product for multiple language

{“de”: “”, “en”: “Example of a short description”, “es”: “”, “fr”: “Description rapide exemple.”}

description

N

JSON object

Descrition of the category for multiple languages

{“de”: “”, “en”: “Tours Category”, “es”: “Categoría de Tours”, “fr”: “Catégorie de Tours”}

experienceHighlights

N

JSON object

What are the highlight for the product?

{“fr”: “Un spectacle exceptionnelnUne expérience inoubliable”, “en”: “An exceptional shownAn unforgettable experience”, “es”: “Un espectáculo excepcionalnUna experiencia inolvidable”, “de”: “Eine außergewöhnliche ShownEin unvergessliches Erlebnis”}

thumbnailImage

N

string[255]

Link to the product thumbnail image

 http://cdn.com/img.jpg

bookingEngine

N

string[255]

Name of the Booking Engine related to the product

[ELLOHA, REGIONDO, VIATOR, BOOKINGKIT, HOLIBOB, DISCOVER, SHERPA, TRIPADVISOR, GOOGLEPLACES, VAKARIO, VAOLO, ALLIANCE_RESEAUX, TICKETAC, APIDAE, MANAWA, GURUWALK, TRAVEL_CURIOUS]

bookingUrl

N

JSON object

Product booking url for each of language provided

{“de”: “”, “en”: “http://www.partner.viator.com/en/13257/tours/Mallorca/Sailing-Baptism-in-Cala-Major/d955-130723P3”, “es”: “”, “fr”: “”}

minPrice

N

float

Product minimum price

10.5

maxPrice

N

float

Product maximum prince

95.8

priceCurrency

N

string[3]

Product price currency ISO 4217

[ “EUR”, “USD”, “CAD”, “AUD” etc… ]

pricingUnit

N

string[255]

Product princing unit

[ PER_PERSON, PER_VEHICLE, GROUP, FAMILY, PER_EQUIPMENT, PACKAGE, PER_BOAT ]

priceLevel

N

integer

Price level of a product as quartile ranging in [1-4]

2

averagePrice

N

float

Average price (was designed to get an average price of a meal at a restaurant)

32.8

minParticipants

N

integer

Minimum number of participants for the product

2

maxParticipants

N

integer

Maximum number of participants for the product

10

address

N

string[512]

Address of the product

3 place Aristide Briand 44000 Nantes

placeId

N

string[255]

Google place ID

ChIJDaf_HzbbzRIReWzukxGqaFc

website

N

string[512]

Website of the product

 https://www.tripadvisor.fr/Attraction_Review-g187224-d19925761-Reviews-Monument_aux_Morts-Grasse_French_Riviera_Cote_d_Azur_Provence_Alpes_Cote_d_Azur.html

geoLocation

N

JSON object

Geolocation data for the product

{ “latitude”: 29.976, “longitude”: 31.1313, “geoHash”: “u09wh9nfs998797” }

geoLocation/latitude

N

float

Latitude of the supplier address

29.976

geoLocation/longitude

N

float

Longitude of the supplier address

31.1313

geoLocation/geoHash

N

string

public domain geocode system encodes a geographic location into a short string of letters and digits (it encodes a geographic location into a short string of letters and digits)

u09wh9nfs998797

duration

N

string[255]

Duration (ISO 8601)

P0DT7H0M0S

galleryImage

N

JSON object

Images data and metadata for the product

[ { “title”: “image1”, “url”: “https://photo.com/images/image0.jpg”, “order”: 0 }, { … }, … ]

galleryImages/title

N

string

image title for the product

Kayak ride

galleryImages/url

N

string

image url for the product

https://…

galleryImages/order

N

integer

image position in gallery for the product

0

categories

N

JSON object

Categories data and metadata for the product

[ { “level”: 1, “code”: “museums” }, { … }, … ]

categories/level

N

integer

1 indicates there is one categories 2 indicates there is subcategories 3

1

categories/code

N

string

Category code

boat_tours_water_sports

categories/name

N

JSON object

Category name

{“de”: “Tours”, “en”: “Tours”, “es”: “Tours”, “fr”: “Tours”}

categories/description

N

JSON object

Category description for multiple languages

{“de”: “”, “en”: “Tours Category”, “es”: “Categoría de Tours”, “fr”: “Catégorie de Tours”}

availabilityPeriods

N

JSON object

Availability & opening hours

“availabilityPeriods”: { “weeklyPeriods”: [ … ], “spontaneousPeriod”: { … } }

availabilityPeriods/weeklyPeriods

N

JSON array

Describe the weekly availability or opening hours span of a product/shop

“weeklyPeriods”: [{“description”:”Summertime opening”,”startDate”:”2023-07-01”,”endDate”:”2023-08-31”,”sunday”:{“open”:true,”hours”:null},”monday”:{“open”:true,”hours”:null},”tuesday”:{“open”:true,”hours”:null},”wednesday”:{“open”:true,”hours”:null},”thursday”:{“open”:true,”hours”:null},”friday”:{“open”:true,”hours”:null},”saturday”:{“open”:true,”hours”:null},”closedDayList”:[“2023-07-14”,”2023-08-15”]}]

availabilityPeriods/spontaneousPeriod

N

JSON object

Describe a list of event start time as ISO datetime

{“spontaneousPeriod”:{“description”:”Opera 2 weeks performance and Special 31st august night”,”eventDateList”:[“2023-08-02T20:00”,”2023-08-03T20:00”,”2023-08-04T20:00”,”2023-08-05T20:00”,”2023-08-06T20:00”,”2023-08-09T20:00”,”2023-08-10T20:00”,”2023-08-11T20:00”,”2023-08-12T20:00”,”2023-08-13T20:00”,”2023-08-31T19:00”,”2023-08-31T23:00”]}}

onlineBookable

N/A

boolean

autogenerated

true

isCancellable

N

boolean

Is the product cancellable?

true

cancellationCutOffAmount

N

integer

The numeric amount for the cutoff

7

cancellationCutOffUnit

N

string

Time units used to determine duration. Three values are available: [hour minute day]

hour

cancellationCutOff

N

JSON object

This is how long before the tour the booking can be still be cancelled

{“fr”: “2 heures”, “en”: “2 hours”, “es”: “2 horas”, “de”: “2 Stunden” }

handiAccess

N

boolean

Is this product handicapped accessible?

true

modalitiesIncluded

N

JSON object

What is included in this product?

{“fr”: “Le transport est inclu”, “en”: “Transportation is included”, “es”: “El transporte está incluido”, “de”: “Der Transport ist inbegriffen”}

modalitiesExcluded

N

JSON object

What is excluded in this product?

{“fr”: “Les boissons sont exclues”, “en”: “Beverages are excluded”, “es”: “Las bebidas están excluidas”, “de”: “Getränke sind ausgeschlossen”}

modalitiesAdditionalInfo

N

JSON object

What are the additionnal info for the product?

{“fr”: “Prévoyez un parapluie”, “en”: “Bring an umbrella”, “es”: “Lleva un paraguas”, “de”: “Bringe einen Regenschirm mit”}

estCommNet

N

float

Estimated commission net

2.3

estCommFrpricePerc

N

float

Estimated commission from retail price ratio

0.10

metadata

N

JSON object

JSON field to add meta data

{“categories”: [“Activities”]}

Output

Response Body Example
{
"id": 7844007,
"creationDate": "2022-08-25T13:07:04.573+00:00",
"title": {
    "de": "meine Prüfungen in verschiedenen Sprachen",
    "en": "my tests in different languages",
    "fr": "mes tests dans différentes langues",
    "es": "mis test en diferentes idiomas "
},
"externalId": "test-regresion 1661432825",
"channel": "ALENTOUR",
"internalName": "test-demo-demo",
"reference": "test-demo-demo",
"instantConfirmation": true,
"instantDelivery": true,
"availabilityType": "START_TIME",
"redemptionMethod": "MANIFEST",
"subtitle": {
    "de": "meine Prüfungen in verschiedenen Sprachen",
    "en": "my tests in different languages",
    "fr": "mes tests dans différentes langues",
    "es": "mis test en diferentes idiomas "
},
"shortDescription": {
    "de": "meine Prüfungen in verschiedenen Sprachen",
    "en": "my tests in different languages",
    "fr": "mes tests dans différentes langues",
    "es": "mis test en diferentes idiomas "
},
"description": {
    "de": "meine Prüfungen in verschiedenen Sprachen",
    "en": "my tests in different languages",
    "fr": "mes tests dans différentes langues",
    "es": "mis test en diferentes idiomas "
},
"bookingEngine": "SHERPA",
"bookingUrl": {
    "de": "www.test.com",
    "en": "www.test.com",
    "fr": "www.test.com",
    "es": "www.test.com"
},
"minPrice": 20.0,
"maxPrice": 40.0,
"priceCurrency": "USD",
"pricingUnit": "GROUP",
"minParticipants": 1,
"maxParticipants": 2,
"address": "Calle test, Madrid",
"cityName": "Madrid",
"country": {
    "code": "ES",
    "name": {
        "de": "Spanien",
        "en": "Spain",
        "fr": "Espagne",
        "es": "España"
    }
},
"zipCode": "07526",
"placeId": "JASD87DHADID7DDAUHD",
"website": "www.test.com",
"geoLocation": {
    "latitude": 40.4377114,
    "longitude": -3.7755088,
    "geoHash": "ezjq416y8rb8"
},
"duration": "PT3H30M",
"galleryImages": [
    {
        "title": "CORGI",
        "url": "https://estaticos.muyinteresante.es/media/cache/1000x_thumb/uploads/images/gallery/5b1f82135bafe8e0fbeffd4f/corgi-con-palo.jpg",
        "order": 0
    }
],
"categories": [
    {
        "level": 1,
        "code": "museums"
    }
],
"onlineBookable": {
    "de": true,
    "en": true,
    "fr": true,
    "es": true
},
"rating": 4.75,
"numberOfRatings": 123456,
"priceLevel": 3,
"averagePrice": 60.99
}

Status code

Code

Description

201

Product created successfully

400

Bad request (non numeric supplier id)

400

Product externalId already exists

400

Not supported currency / invalid ISO 4217 code

401

Unauthorized

403

Forbidden

404

Non existing supplier

500

Internal Server Error

Note

Note: IF a product is pushed with parameters (supplierId=234, externalId=”uniqID”) AND our DB already holds a product identified with the same externalId=”uniqID” but with a different supplierId=123, THEN we will update the product supplierId with the new one.

Retrieve a product#

Path

GET /api/supplier/{supplierId}/products/

Input parameters

Table 7 - Description of the input parameters in the “Retrieve a product” endpoint#

Field

Mandatory

Type

Description

Example

supplierId

Y

integer

Identifier of the supplier which provides the product

8214

countryCode

N

string[2]

Iso 3166-alpha2 country code

FR

zipCode

N

string[20]

Zip code

75011

rating

N

float

Feed the rating (range is [0-5])

3.8

numberOfRatings

N

integer

Feed the rating count

3276

cityName

N

string[255]

City name

Paris

Output

Response Body Example
[
    {
        "id": 7844001,
        "creationDate": "2022-08-25T13:06:56.070+00:00",
        "title": {
            "de": "meine Prüfungen in verschiedenen Sprachen",
            "en": "my tests in different languages",
            "fr": "mes tests dans différentes langues",
            "es": "mis test en diferentes idiomas "
        },
        "externalId": "test-regresion 1661432816",
        "channel": "ALENTOUR",
        "internalName": "test-demo-demo",
        "reference": "test-demo-demo",
        "instantConfirmation": true,
        "instantDelivery": true,
        "availabilityType": "START_TIME",
        "redemptionMethod": "MANIFEST",
        "subtitle": {
            "de": "meine Prüfungen in verschiedenen Sprachen",
            "en": "my tests in different languages",
            "fr": "mes tests dans différentes langues",
            "es": "mis test en diferentes idiomas "
        },
        "shortDescription": {
            "de": "meine Prüfungen in verschiedenen Sprachen",
            "en": "my tests in different languages",
            "fr": "mes tests dans différentes langues",
            "es": "mis test en diferentes idiomas "
        },
        "description": {
            "de": "meine Prüfungen in verschiedenen Sprachen",
            "en": "my tests in different languages",
            "fr": "mes tests dans différentes langues",
            "es": "mis test en diferentes idiomas "
        },
        "thumbnailImage": "465dd2f7-9b18-4e02-b8cc-29165d756448",
        "bookingEngine": "SHERPA",
        "bookingUrl": {
            "de": "www.test.com",
            "en": "www.test.com",
            "fr": "www.test.com",
            "es": "www.test.com"
        },
        "minPrice": 20.0,
        "maxPrice": 40.0,
        "priceCurrency": "USD",
        "pricingUnit": "GROUP",
        "minParticipants": 1,
        "maxParticipants": 2,
        "address": "Calle test, Madrid",
        "cityName": "Madrid",
        "country": {
            "code": "ES",
            "name": {
                "de": "Spanien",
                "en": "Spain",
                "fr": "Espagne",
                "es": "España"
            }
        },
        "zipCode": "07526",
        "placeId": "JASD87DHADID7DDAUHD",
        "website": "www.test.com",
        "geoLocation": {
            "latitude": 40.4377114,
            "longitude": -3.7755088,
            "geoHash": "ezjq416y8rb8"
        },
        "duration": "PT3H30M",
        "galleryImages": [
            {
                "title": "CORGI",
                "url": "https://estaticos.muyinteresante.es/media/cache/1000x_thumb/uploads/images/gallery/5b1f82135bafe8e0fbeffd4f/corgi-con-palo.jpg",
                "order": 0
            }
        ],
        "categories": [
            {
                "level": 1,
                "code": "museums"
            }
        ],
        "onlineBookable": {
            "de": true,
            "en": true,
            "fr": true,
            "es": true
        },
        "rating": 4.75,
        "numberOfRatings": 123456
    },
    {
        "id": 7879381,
        "creationDate": "2022-08-26T07:52:58.583+00:00",
        "title": {
            "de": "meine Prüfungen in verschiedenen Sprachen",
            "en": "my tests in different languages",
            "fr": "mes tests dans différentes langues",
            "es": "mis test en diferentes idiomas "
        },
        "externalId": "test-regresion 1661500378",
        "channel": "ALENTOUR",
        "internalName": "test-demo-demo",
        "reference": "test-demo-demo",
        "instantConfirmation": true,
        "instantDelivery": true,
        "availabilityType": "START_TIME",
        "redemptionMethod": "MANIFEST",
        "subtitle": {
            "de": "meine Prüfungen in verschiedenen Sprachen",
            "en": "my tests in different languages",
            "fr": "mes tests dans différentes langues",
            "es": "mis test en diferentes idiomas "
        },
        "shortDescription": {
            "de": "meine Prüfungen in verschiedenen Sprachen",
            "en": "my tests in different languages",
            "fr": "mes tests dans différentes langues",
            "es": "mis test en diferentes idiomas "
        },
        "description": {
            "de": "meine Prüfungen in verschiedenen Sprachen",
            "en": "my tests in different languages",
            "fr": "mes tests dans différentes langues",
            "es": "mis test en diferentes idiomas "
        },
        "thumbnailImage": "79573aa7-15f7-4c8b-872f-d2d102c4742d",
        "bookingEngine": "SHERPA",
        "bookingUrl": {
            "de": "www.test.com",
            "en": "www.test.com",
            "fr": "www.test.com",
            "es": "www.test.com"
        },
        "minPrice": 20.0,
        "maxPrice": 40.0,
        "priceCurrency": "USD",
        "pricingUnit": "GROUP",
        "minParticipants": 1,
        "maxParticipants": 2,
        "address": "Calle test, Madrid",
        "cityName": "Madrid",
        "country": {
            "code": "ES",
            "name": {
                "de": "Spanien",
                "en": "Spain",
                "fr": "Espagne",
                "es": "España"
            }
        },
        "zipCode": "07526",
        "placeId": "JASD87DHADID7DDAUHD",
        "website": "www.test.com",
        "geoLocation": {
            "latitude": 40.4377114,
            "longitude": -3.7755088,
            "geoHash": "ezjq416y8rb8"
        },
        "duration": "PT3H30M",
        "galleryImages": [
            {
                "title": "CORGI",
                "url": "https://estaticos.muyinteresante.es/media/cache/1000x_thumb/uploads/images/gallery/5b1f82135bafe8e0fbeffd4f/corgi-con-palo.jpg",
                "order": 0
            }
        ],
        "categories": [
            {
                "level": 1,
                "code": "museums"
            }
        ],
        "onlineBookable": {
            "de": true,
            "en": true,
            "fr": true,
            "es": true
        },
        "rating": 4.75,
        "numberOfRatings": 123456,
        "priceLevel": 1
    }
]

Status code

Code

Description

200

Successful retrieval of supplier products

400

Bad request (non numeric supplier id)

401

Unauthorized

403

Forbidden

404

Non existing supplier

500

Internal Server Error

Update a product#

Path

POST /api/supplier/{supplierId}/product/{productId}

Input parameters

Table 8 - Description of the input parameters in the “Update a product” endpoint#

Field

Mandatory

Type

Description

Example

supplierId

Y

integer

Identifier of the supplier which provides the product

8214

productId

Y

integer

Identifier of the product to update

14152

externalId

N

string[255]

Identifier of the supplier

title

N

JSON object

Name of the product per language

{“de”: “Kayak Paddle”, “en”: “”, “es”: “Kayak Paddle”, “fr”: “Kayak Paddle”}

countryCode

N

string[2]

Iso 3166-alpha2 country code

FR

zipCode

N

string[20]

Zip code

75011

rating

N

float

Feed the rating average (range is [0-5])

3.8

numberOfRatings

N

integer

Feed the rating count

3276

cityName

N

string[255]

City name

Paris

id

N/A

integer

autogenerated

0

creationDate

N/A

date

autogenerated

2022-03-29T09:10:30.931Z

channel

N

string[32]

Identifies the channel through which the supplier uploads the content for our application

ALENTOUR

internalName

N

string[255]

Supplier name

Kayak-Evasion

reference

N

string[255]

Same as externalId

LR1-01

instantConfirmation

N

boolean

Instant confirmation boolean

true

instantDelivery

N

boolean

Instant delivery boolean

true

availabilityType

N

string[255]

Describes how availability is designed for this product

[ START_TIME, OPENING_HOURS ]

redemptionMethod

N

string[255]

Information about redemption methods available for this product

[ MANIFEST, DIGITAL, PRINT ]

subtitle

N

JSON object

Subtitle of the product

{“de”: “Kayak Paddle”, “en”: “ Stand up paddle in the Mediterean Sea “, “es”: “Kayak Paddle en el Mar Mediteraneo”, “fr”: “Kayak Paddle”}

shortDescription

N

JSON object

Short description/presentation of the product for multiple language

{“de”: “”, “en”: “Example of a short description”, “es”: “”, “fr”: “Description rapide exemple.”}

description

N

JSON object

Descrition of the category for multiple languages

{“de”: “”, “en”: “Tours Category”, “es”: “Categoría de Tours”, “fr”: “Catégorie de Tours”}

experienceHighlights

N

JSON object

What are the highlight for the product?

{“fr”: “Un spectacle exceptionnelnUne expérience inoubliable”, “en”: “An exceptional shownAn unforgettable experience”, “es”: “Un espectáculo excepcionalnUna experiencia inolvidable”, “de”: “Eine außergewöhnliche ShownEin unvergessliches Erlebnis”}

thumbnailImage

N

string[255]

Link to the product thumbnail image

 http://cdn.com/img.jpg

bookingEngine

N

string[255]

Name of the Booking Engine related to the product

[ELLOHA, REGIONDO, VIATOR, BOOKINGKIT, HOLIBOB, DISCOVER, SHERPA, TRIPADVISOR, GOOGLEPLACES, VAKARIO, VAOLO, ALLIANCE_RESEAUX, TICKETAC, APIDAE, MANAWA, GURUWALK, TRAVEL_CURIOUS]

bookingUrl

N

JSON object

Product booking url for each of language provided

{“de”: “”, “en”: “http://www.partner.viator.com/en/13257/tours/Mallorca/Sailing-Baptism-in-Cala-Major/d955-130723P3”, “es”: “”, “fr”: “”}

minPrice

N

float

Product minimum price

10.5

maxPrice

N

float

Product maximum prince

95.8

priceCurrency

N

string[3]

Product price currency ISO 4217

[ “EUR”, “USD”, “CAD”, “AUD” etc… ]

pricingUnit

N

string[255]

Product princing unit

[ PER_PERSON, PER_VEHICLE, GROUP, FAMILY, PER_EQUIPMENT, PACKAGE, PER_BOAT ]

priceLevel

N

integer

Price level of a product as quartile ranging in [1-4]

2

averagePrice

N

float

Average price (was designed to get an average price of a meal at a restaurant)

32.8

minParticipants

N

integer

Minimum number of participants for the product

2

maxParticipants

N

integer

Maximum number of participants for the product

10

address

N

string[512]

Address of the product

3 place Aristide Briand 44000 Nantes

placeId

N

string[255]

Google place ID

ChIJDaf_HzbbzRIReWzukxGqaFc

website

N

string[512]

Website of the product

 https://www.tripadvisor.fr/Attraction_Review-g187224-d19925761-Reviews-Monument_aux_Morts-Grasse_French_Riviera_Cote_d_Azur_Provence_Alpes_Cote_d_Azur.html

geoLocation

N

JSON object

Geolocation data for the product

{ “latitude”: 29.976, “longitude”: 31.1313, “geoHash”: “u09wh9nfs998797” }

geoLocation/latitude

N

float

Latitude of the supplier address

29.976

geoLocation/longitude

N

float

Longitude of the supplier address

31.1313

geoLocation/geoHash

N

string

public domain geocode system encodes a geographic location into a short string of letters and digits (it encodes a geographic location into a short string of letters and digits)

u09wh9nfs998797

duration

N

string[255]

Duration (ISO 8601)

P0DT7H0M0S

galleryImage

N

JSON object

Images data and metadata for the product

[ { “title”: “image1”, “url”: “https://photo.com/images/image0.jpg”, “order”: 0 }, { … }, … ]

galleryImages/title

N

string

image title for the product

Kayak ride

galleryImages/url

N

string

image url for the product

https://…

galleryImages/order

N

integer

image position in gallery for the product

0

categories

N

JSON object

Categories data and metadata for the product

[ { “level”: 1, “code”: “museums” }, { … }, … ]

categories/level

N

integer

1 indicates there is one categories 2 indicates there is subcategories 3

1

categories/code

N

string

Category code

boat_tours_water_sports

categories/name

N

JSON object

Category name

{“de”: “”, “en”: “Tours “, “es”: “Tours”, “fr”: “ Tours”}

categories/description

N

JSON object

Category description for multiple languages

{“de”: “”, “en”: “Tours Category”, “es”: “Categoría de Tours”, “fr”: “Catégorie de Tours”}

availabilityPeriods

N

JSON object

Availability & opening hours

“availabilityPeriods”: { “weeklyPeriods”: [ … ], “spontaneousPeriod”: { … } }

availabilityPeriods/weeklyPeriods

N

JSON array

Describe the weekly availability or opening hours span of a product/shop

“weeklyPeriods”: [{“description”:”Summertime opening”,”startDate”:”2023-07-01”,”endDate”:”2023-08-31”,”sunday”:{“open”:true,”hours”:null},”monday”:{“open”:true,”hours”:null},”tuesday”:{“open”:true,”hours”:null},”wednesday”:{“open”:true,”hours”:null},”thursday”:{“open”:true,”hours”:null},”friday”:{“open”:true,”hours”:null},”saturday”:{“open”:true,”hours”:null},”closedDayList”:[“2023-07-14”,”2023-08-15”]}]

availabilityPeriods/spontaneousPeriod

N

JSON object

Describe a list of event start time as ISO datetime

{“spontaneousPeriod”:{“description”:”Opera 2 weeks performance and Special 31st august night”,”eventDateList”:[“2023-08-02T20:00”,”2023-08-03T20:00”,”2023-08-04T20:00”,”2023-08-05T20:00”,”2023-08-06T20:00”,”2023-08-09T20:00”,”2023-08-10T20:00”,”2023-08-11T20:00”,”2023-08-12T20:00”,”2023-08-13T20:00”,”2023-08-31T19:00”,”2023-08-31T23:00”]}}

onlineBookable

N/A

boolean

autogenerated

true

isCancellable

N

boolean

Is the product cancellable?

true

cancellationCutOffAmount

N

integer

The numeric amount for the cutoff

7

cancellationCutOffUnit

N

string

Time units used to determine duration. Three values are available: [hour minute day]

hour

cancellationCutOff

N

JSON object

This is how long before the tour the booking can be still be cancelled

{“fr”: “2 heures”, “en”: “2 hours”, “es”: “2 horas”, “de”: “2 Stunden” }

handiAccess

N

boolean

Is this product handicapped accessible?

true

modalitiesIncluded

N

JSON object

What is included in this product?

{“fr”: “Le transport est inclu”, “en”: “Transportation is included”, “es”: “El transporte está incluido”, “de”: “Der Transport ist inbegriffen”}

modalitiesExcluded

N

JSON object

What is excluded in this product?

{“fr”: “Les boissons sont exclues”, “en”: “Beverages are excluded”, “es”: “Las bebidas están excluidas”, “de”: “Getränke sind ausgeschlossen”}

modalitiesAdditionalInfo

N

JSON object

What are the additionnal info for the product?

{“fr”: “Prévoyez un parapluie”, “en”: “Bring an umbrella”, “es”: “Lleva un paraguas”, “de”: “Bringe einen Regenschirm mit”}

estCommNet

N

float

Estimated commission net

2.3

estCommFrpricePerc

N

float

Estimated commission from retail price ratio

0.10

metadata

N

JSON object

JSON field to add meta data

{“categories”: [“Activities”]}

Output

Response Body Example
{
    "id": 7844007,
    "creationDate": "2022-08-25T13:07:04.573+00:00",
    "updateDate": "2022-08-25T13:07:30.196+00:00",
    "title": {
        "de": "meine Prüfungen in verschiedenen Sprachen",
        "en": "my tests in different languages",
        "fr": "mes tests dans différentes langues",
        "es": "mis test en diferentes idiomas "
    },
    "externalId": "test-demo-demo 1661432850",
    "channel": "DISCOVER",
    "internalName": "test-demo-demo",
    "reference": "test-demo-demo",
    "instantConfirmation": true,
    "instantDelivery": true,
    "availabilityType": "START_TIME",
    "redemptionMethod": "MANIFEST",
    "subtitle": {
        "de": "meine Prüfungen in verschiedenen Sprachen",
        "en": "my tests in different languages",
        "fr": "mes tests dans différentes langues",
        "es": "mis test en diferentes idiomas "
    },
    "shortDescription": {
        "de": "meine Prüfungen in verschiedenen Sprachen",
        "en": "my tests in different languages",
        "fr": "mes tests dans différentes langues",
        "es": "mis test en diferentes idiomas "
    },
    "description": {
        "de": "meine Prüfungen in verschiedenen Sprachen",
        "en": "my tests in different languages",
        "fr": "mes tests dans différentes langues",
        "es": "mis test en diferentes idiomas "
    },
    "thumbnailImage": "a90dbdeb-06d1-4213-84a6-435d51173612",
    "bookingEngine": "SHERPA",
    "bookingUrl": {
        "de": "www.test.de",
        "en": "www.test.com",
        "fr": "www.test.fr",
        "es": "www.test.es"
    },
    "minPrice": 20.0,
    "maxPrice": 40.0,
    "priceCurrency": "USD",
    "pricingUnit": "GROUP",
    "minParticipants": 1,
    "maxParticipants": 2,
    "address": "Calle test, Madrid",
    "cityName": "Troyes",
    "country": {
        "code": "FR",
        "name": {
            "de": "Frankreich",
            "en": "France",
            "fr": "France",
            "es": "Francia"
        }
    },
    "zipCode": "10300",
    "placeId": "JASD87DHADID7DDAUHD",
    "website": "www.test.com",
    "geoLocation": {
        "latitude": 40.4377114,
        "longitude": -3.7755088,
        "geoHash": "ezjq416y8rb8"
    },
    "duration": "PT3H30M",
    "galleryImages": [
        {
            "title": "CORGI",
            "url": "https://estaticos.muyinteresante.es/media/cache/1000x_thumb/uploads/images/gallery/5b1f82135bafe8e0fbeffd4f/corgi-con-palo.jpg",
            "order": 0
        }
    ],
    "categories": [
        {
            "level": 1,
            "code": "tours"
        }
    ],
    "onlineBookable": {
        "de": false,
        "en": true,
        "fr": false,
        "es": true
    },
    "rating": 3.859,
    "numberOfRatings": 4589,
    "priceLevel": 2,
    "averagePrice": 25.6
}

Status code

Code

Description

200

Product updated successfully

400

Bad request (non numeric supplier id)

400

Bad request (non numeric product id)

400

Bad request (non numeric supplier id)

400

Product externalId already exists

400

Not supported currency / invalid ISO 4217 code

401

Unauthorized

403

Forbidden

404

Non existing supplier

404

Non existing product

500

Internal Server Error

Note

Note: In the case the ProductID is not linked to the right SupplierID, the request will fail. An error message will be sent.

Note: This endpoint allow a “full update” of the product, meaning non supplied field will be reset with null value. for a partial update keeping unchanged fields you may want to use the PATCH method.


Update a product - PATCH method#

Path

PATCH /api/supplier/{supplierId}/product/{productId}

Input parameters

Input methodology:

Internally we use : JSON Patch as specified in RFC 6902 from the IETF. (https://jsonpatch.com/)

Note

Call must use a formated Content-Type: application/json-patch+json in the endpoint, else server will bounce an error 415

Patch update body example:

[
  {
      "op": "add",
      "path": "/onlineBookable/it",
      "value": false
  },
  {
      "op": "replace",
      "path": "/onlineBookable/de",
      "value": true
  }
]
Table 9 - Description of the input parameters in the “Update a product” endpoint#

Field

Mandatory

Type

Description

Example

supplierId

Y

integer

Identifier of the supplier which provides the product

8214

productId

Y

integer

Identifier of the product to update

14152

externalId

N

string[255]

Identifier of the supplier

title

N

JSON object

Name of the product per language

{“de”: “Kayak Paddle”, “en”: “”, “es”: “Kayak Paddle”, “fr”: “Kayak Paddle”}

countryCode

N

string[2]

Iso 3166-alpha2 country code

FR

zipCode

N

string[20]

Zip code

75011

rating

N

float

Feed the rating average (range is [0-5])

3.8

numberOfRatings

N

integer

Feed the rating count

3276

cityName

N

string[255]

City name

Paris

id

N/A

integer

autogenerated

0

creationDate

N/A

date

autogenerated

2022-03-29T09:10:30.931Z

channel

N

string[32]

Identifies the channel through which the supplier uploads the content for our application

ALENTOUR

internalName

N

string[255]

Supplier name

Kayak-Evasion

reference

N

string[255]

Same as externalId

LR1-01

instantConfirmation

N

boolean

Instant confirmation boolean

true

instantDelivery

N

boolean

Instant delivery boolean

true

availabilityType

N

string[255]

Describes how availability is designed for this product

[ START_TIME, OPENING_HOURS ]

redemptionMethod

N

string[255]

Information about redemption methods available for this product

[ MANIFEST, DIGITAL, PRINT ]

subtitle

N

JSON object

Subtitle of the product

{“de”: “Kayak Paddle”, “en”: “ Stand up paddle in the Mediterean Sea “, “es”: “Kayak Paddle en el Mar Mediteraneo”, “fr”: “Kayak Paddle”}

shortDescription

N

JSON object

Short description/presentation of the product for multiple language

{“de”: “”, “en”: “Example of a short description”, “es”: “”, “fr”: “Description rapide exemple.”}

description

N

JSON object

Descrition of the category for multiple languages

{“de”: “”, “en”: “Tours Category”, “es”: “Categoría de Tours”, “fr”: “Catégorie de Tours”}

experienceHighlights

N

JSON object

What are the highlight for the product?

{“fr”: “Un spectacle exceptionnelnUne expérience inoubliable”, “en”: “An exceptional shownAn unforgettable experience”, “es”: “Un espectáculo excepcionalnUna experiencia inolvidable”, “de”: “Eine außergewöhnliche ShownEin unvergessliches Erlebnis”}

thumbnailImage

N

string[255]

Link to the product thumbnail image

 http://cdn.com/img.jpg

bookingEngine

N

string[255]

Name of the Booking Engine related to the product

[ELLOHA, REGIONDO, VIATOR, BOOKINGKIT, HOLIBOB, DISCOVER, SHERPA, TRIPADVISOR, GOOGLEPLACES, VAKARIO, VAOLO, ALLIANCE_RESEAUX, TICKETAC, APIDAE, MANAWA, GURUWALK, TRAVEL_CURIOUS]

bookingUrl

N

JSON object

Product booking url for each of language provided

{“de”: “”, “en”: “http://www.partner.viator.com/en/13257/tours/Mallorca/Sailing-Baptism-in-Cala-Major/d955-130723P3”, “es”: “”, “fr”: “”}

minPrice

N

float

Product minimum price

10.5

maxPrice

N

float

Product maximum prince

95.8

priceCurrency

N

string[3]

Product price currency ISO 4217

[ “EUR”, “USD”, “CAD”, “AUD” etc… ]

pricingUnit

N

string[255]

Product princing unit

[ PER_PERSON, PER_VEHICLE, GROUP, FAMILY, PER_EQUIPMENT, PACKAGE, PER_BOAT ]

priceLevel

N

integer

Price level of a product as quartile ranging in [1-4]

2

averagePrice

N

float

Average price (was designed to get an average price of a meal at a restaurant)

32.8

minParticipants

N

integer

Minimum number of participants for the product

2

maxParticipants

N

integer

Maximum number of participants for the product

10

address

N

string[512]

Address of the product

3 place Aristide Briand 44000 Nantes

placeId

N

string[255]

Google place ID

ChIJDaf_HzbbzRIReWzukxGqaFc

website

N

string[512]

Website of the product

 https://www.tripadvisor.fr/Attraction_Review-g187224-d19925761-Reviews-Monument_aux_Morts-Grasse_French_Riviera_Cote_d_Azur_Provence_Alpes_Cote_d_Azur.html

geoLocation

N

JSON object

Geolocation data for the product

{ “latitude”: 29.976, “longitude”: 31.1313, “geoHash”: “u09wh9nfs998797” }

geoLocation/latitude

N

float

Latitude of the supplier address

29.976

geoLocation/longitude

N

float

Longitude of the supplier address

31.1313

geoLocation/geoHash

N

string

public domain geocode system encodes a geographic location into a short string of letters and digits (it encodes a geographic location into a short string of letters and digits)

u09wh9nfs998797

duration

N

string[255]

Duration (ISO 8601)

P0DT7H0M0S

galleryImage

N

JSON object

Images data and metadata for the product

[ { “title”: “image1”, “url”: “https://photo.com/images/image0.jpg”, “order”: 0 }, { … }, … ]

galleryImages/title

N

string

image title for the product

Kayak ride

galleryImages/url

N

string

image url for the product

https://…

galleryImages/order

N

integer

image position in gallery for the product

0

categories

N

JSON object

Categories data and metadata for the product

[ { “level”: 1, “code”: “museums” }, { … }, … ]

categories/level

N

integer

1 indicates there is one categories 2 indicates there is subcategories 3

1

categories/code

N

string

Category code

boat_tours_water_sports

categories/name

N

JSON object

Category name

{“de”: “”, “en”: “Tours “, “es”: “Tours”, “fr”: “ Tours”}

categories/description

N

JSON object

Category description for multiple languages

{“de”: “”, “en”: “Tours Category”, “es”: “Categoría de Tours”, “fr”: “Catégorie de Tours”}

availabilityPeriods

N

JSON object

Availability & opening hours

“availabilityPeriods”: { “weeklyPeriods”: [ … ], “spontaneousPeriod”: { … } }

availabilityPeriods/weeklyPeriods

N

JSON array

Describe the weekly availability or opening hours span of a product/shop

“weeklyPeriods”: [{“description”:”Summertime opening”,”startDate”:”2023-07-01”,”endDate”:”2023-08-31”,”sunday”:{“open”:true,”hours”:null},”monday”:{“open”:true,”hours”:null},”tuesday”:{“open”:true,”hours”:null},”wednesday”:{“open”:true,”hours”:null},”thursday”:{“open”:true,”hours”:null},”friday”:{“open”:true,”hours”:null},”saturday”:{“open”:true,”hours”:null},”closedDayList”:[“2023-07-14”,”2023-08-15”]}]

availabilityPeriods/spontaneousPeriod

N

JSON object

Describe a list of event start time as ISO datetime

{“spontaneousPeriod”:{“description”:”Opera 2 weeks performance and Special 31st august night”,”eventDateList”:[“2023-08-02T20:00”,”2023-08-03T20:00”,”2023-08-04T20:00”,”2023-08-05T20:00”,”2023-08-06T20:00”,”2023-08-09T20:00”,”2023-08-10T20:00”,”2023-08-11T20:00”,”2023-08-12T20:00”,”2023-08-13T20:00”,”2023-08-31T19:00”,”2023-08-31T23:00”]}}

onlineBookable

N/A

boolean

autogenerated

true

isCancellable

N

boolean

Is the product cancellable?

true

cancellationCutOffAmount

N

integer

The numeric amount for the cutoff

7

cancellationCutOffUnit

N

string

Time units used to determine duration. Three values are available: [hour minute day]

hour

cancellationCutOff

N

JSON object

This is how long before the tour the booking can be still be cancelled

{“fr”: “2 heures”, “en”: “2 hours”, “es”: “2 horas”, “de”: “2 Stunden” }

handiAccess

N

boolean

Is this product handicapped accessible?

true

modalitiesIncluded

N

JSON object

What is included in this product?

{“fr”: “Le transport est inclu”, “en”: “Transportation is included”, “es”: “El transporte está incluido”, “de”: “Der Transport ist inbegriffen”}

modalitiesExcluded

N

JSON object

What is excluded in this product?

{“fr”: “Les boissons sont exclues”, “en”: “Beverages are excluded”, “es”: “Las bebidas están excluidas”, “de”: “Getränke sind ausgeschlossen”}

modalitiesAdditionalInfo

N

JSON object

What are the additionnal info for the product?

{“fr”: “Prévoyez un parapluie”, “en”: “Bring an umbrella”, “es”: “Lleva un paraguas”, “de”: “Bringe einen Regenschirm mit”}

estCommNet

N

float

Estimated commission net

2.3

estCommFrpricePerc

N

float

Estimated commission from retail price ratio

0.10

metadata

N

JSON object

JSON field to add meta data

{“categories”: [“Activities”]}

Output

Response Body Example
{
    "id": 7844007,
    "creationDate": "2022-08-25T13:07:04.573+00:00",
    "updateDate": "2022-08-25T13:07:30.196+00:00",
    "title": {
        "de": "meine Prüfungen in verschiedenen Sprachen",
        "en": "my tests in different languages",
        "fr": "mes tests dans différentes langues",
        "es": "mis test en diferentes idiomas "
    },
    "externalId": "test-demo-demo 1661432850",
    "channel": "DISCOVER",
    "internalName": "test-demo-demo",
    "reference": "test-demo-demo",
    "instantConfirmation": true,
    "instantDelivery": true,
    "availabilityType": "START_TIME",
    "redemptionMethod": "MANIFEST",
    "subtitle": {
        "de": "meine Prüfungen in verschiedenen Sprachen",
        "en": "my tests in different languages",
        "fr": "mes tests dans différentes langues",
        "es": "mis test en diferentes idiomas "
    },
    "shortDescription": {
        "de": "meine Prüfungen in verschiedenen Sprachen",
        "en": "my tests in different languages",
        "fr": "mes tests dans différentes langues",
        "es": "mis test en diferentes idiomas "
    },
    "description": {
        "de": "meine Prüfungen in verschiedenen Sprachen",
        "en": "my tests in different languages",
        "fr": "mes tests dans différentes langues",
        "es": "mis test en diferentes idiomas "
    },
    "thumbnailImage": "a90dbdeb-06d1-4213-84a6-435d51173612",
    "bookingEngine": "SHERPA",
    "bookingUrl": {
        "de": "www.test.de",
        "en": "www.test.com",
        "fr": "www.test.fr",
        "es": "www.test.es"
    },
    "minPrice": 20.0,
    "maxPrice": 40.0,
    "priceCurrency": "USD",
    "pricingUnit": "GROUP",
    "minParticipants": 1,
    "maxParticipants": 2,
    "address": "Calle test, Madrid",
    "cityName": "Troyes",
    "country": {
        "code": "FR",
        "name": {
            "de": "Frankreich",
            "en": "France",
            "fr": "France",
            "es": "Francia"
        }
    },
    "zipCode": "10300",
    "placeId": "JASD87DHADID7DDAUHD",
    "website": "www.test.com",
    "geoLocation": {
        "latitude": 40.4377114,
        "longitude": -3.7755088,
        "geoHash": "ezjq416y8rb8"
    },
    "duration": "PT3H30M",
    "galleryImages": [
        {
            "title": "CORGI",
            "url": "https://estaticos.muyinteresante.es/media/cache/1000x_thumb/uploads/images/gallery/5b1f82135bafe8e0fbeffd4f/corgi-con-palo.jpg",
            "order": 0
        }
    ],
    "categories": [
        {
            "level": 1,
            "code": "tours"
        }
    ],
    "onlineBookable": {
        "de": false,
        "en": true,
        "fr": false,
        "es": true
    },
    "rating": 3.859,
    "numberOfRatings": 4589,
    "priceLevel": 2,
    "averagePrice": 25.6
}

Status code

Code

Description

202

Accepted

400

Bad request (non numeric supplier id)

400

Bad request (non numeric product id)

400

Product externalId already exists

400

Not supported currency / invalid ISO 4217 code

401

Unauthorized

403

Forbidden

404

Non existing supplier

404

Non existing product

415

Unsupported Media Type (need a Content-Type: application/json-patch+json)

500

Internal Server Error

Note

Note: In the case the ProductID is not linked to the right SupplierID, the request will fail. An error message will be sent.

Note: This endpoint allow a “partial update” of the product, meaning non supplied field will be unchanged. For a full update you may want to use the POST method.


Remove a product#

Path

DELETE /api/supplier/{supplierId}/product/{productId}

Input parameters

Table 10 - Description of the input parameters in the “Remove a product” endpoint#

Field

Mandatory

Type

Description

Example

supplierId

Y

integer

Identifier of the supplier which provides the product

8214

productId

Y

integer

Identifier of the product to update

14152

Output


Status code

Code

Description

200

Product removed

400

Bad request (non numeric supplierId)

400

Bad request (non numeric productId)

401

Unauthorized

403

Forbidden

404

Non existing supplier

404

Non existing product

500

Internal Server Error

Note

Note: Delete a product is a definitive action that cannot be cancelled. If a product has been deleted by mistake, it will need to be created again.


Deprecate a product#

Path

PUT /api/product/{productExternalId}/deprecated

A product that is temporarily not available for booking can be deprecated using this endpoint.

Deprecated products will be visible in API response, and in Hotelier interface.

Deprecated products can be added in suggestions shared with travellers, but travellers will not be able to see or book them until they are un-deprecated.

The input is the externalId of the product.

Input parameters

Field

Mandatory

Type

Format

Description

Example

productExternalId

Yes

string

N/A

external product of the product

5640456

Output

No output


Status code

Status

Description

201

Product deprecated successfully

400

Scope not found in privileges / User calling the request does not have the right privileges

400

Account does not exist

400

Account is not setup with booking engine

400

Non existing product

400

Product does not have the same booking engine than the requester

400

Product already deprecated

401

Unauthorized

403

Forbidden

404

Non existing supplier / product

500

Internal server error

Undeprecate a product#

Path

DELETE /api/product/{productExternalId}/deprecated

When a product has been deprecated because he was not available, it possible to make it available again using this endpoint.

User can undeprecate only product that belongs to his/her booking engine.

The input is the externalId of the product.

Input parameters

Table 11 - Description of the input parameters in the “Update a product” endpoint#

Field

Mandatory

Type

Format

Description

Example

productExternalId

Y

string

N/A

external product of the product

5640456

Output

No output


Status code

Table 12 - Description of the input parameters in the “Update a product” endpoint#

Status

Description

201

Product un-deprecated successfully

400

Scope not found in privileges / User calling the request does not have the right privileges

400

Account does not exist

400

Account is not setup with booking engine

400

Non existing product

400

Product does not have the same booking engine than the requester

400

Product is not deprecated

401

Unauthorized

403

Forbidden

404

Non existing supplier / product

500

Internal server error

Retrieve supplier products#

This endpoint allows to list all your active products (excluding deprecated or blacklisted products)

Path

GET /api/products

Input parameters

Table 13 - Description of the input parameters in the “Retrieve a product” endpoint#

Field

Mandatory

Type

Description

Example

onlyActive

N

boolean

Retrieve only active product or all products (including deprecated ones)

false (default value)

pageNumber

N

integer

Page number for pagination

1 (default)

resultsPerPage

N

integer

Number of results per page

100 (default)

Output

Response Body Example
{
    "pageNumber": 2,
    "totalResults": 17397,
    "resultsPerPage": 50,
    "items": [
        {
            "id": 3516715,
            "creationDate": "2022-06-14T06:47:38.131+00:00",
            "updateDate": "2022-10-18T06:56:16.212+00:00",
            "title": {
                "de": "Serra da Estrela - Ganztägige Privattour",
                "en": "Serra da Estrela - Full Day Private Tour",
                "fr": "Serra da Estrela - Visite privée d'une journée",
                "es": "Serra da Estrela - Tour privado de día completo"
            },
            "externalId": "0450480c-9c69-4ef8-9692-4ca7510d81d2",
            "channel": "DISCOVER",
            "availabilityType": "OPENING_HOURS",
            "description": {
                "de": "<div><p></p><p>Entdecken Sie die größte Bergkette Portugals, bekannt als Serra da Estrela, ein wahres Wunder der Natur, besonders im Winter, wenn die Pisten vollständig mi",
                "SHORTENED EX": "..."
            }
        }
    ]
}

Status code

Code

Description

200

Successful retrieval of supplier products

400

Offset can’t be negative or equals to zero

400

Results per page can’t be negative or equals to zero

400

User is requesting a wrong booking engine

400

Scope not found in privileges / User calling the request does not have the right privileges

400

Account does not exist

400

Account is not setup with booking engine

400

User is suspended

401

Unauthorized

403

Forbidden

404

Non existing booking engine

500

Internal Server Error

Note

Note: Depecrated (by yourself) or blacklisted (by Amadeus discover) products are not listed on this endpoint response