Tour Service

The tour service provides endpoints that allow access to information about tours. A Tour is something that tracks unique item purchases within a category of items. This can be used to incentivize and reward guests to try new items. An example could be a brewery that wants their patrons to try different styles of beer or a ice cream brand that wants guests try all of their ice cream flavors. All purchase tracking is done through the POS integration; the tour service provides information about the tours available to each guest their progress.

Endpoints

Get Active Tours

GET tour/activeTours.json

Obtains a list of tours that are currently active for a given merchant.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • tours (List[Object]) – (required) The list of tours that are currently active for the merchant. See ActiveTour for the format of these objects.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.

Get Tour Status

GET tour/tourStatus.json

Retrieves a guest’s progress for a given tour.

The following authentication methods are allowed for this endpoint:

Query Parameters:
 
  • merchantId (Integer) – (required) Paytronix-assigned merchant identifier (ID) in which to perform the operation.
  • tourCode (String) – (required) The code uniquely identifying the tour to query.
  • printedCardNumber (String) – (required) Printed card number associated with the account for which to retrieve tour information.
"result": "success"
JSON Parameters:
 
  • result (String) – (required) success
  • firstName (String) – (optional) The guest’s first name if known.
  • lastName (String) – (optional) The guest’s last name if known.
  • tier (String) – (required) The tier of the guest.
  • maskedCardNumber (String) – (required) The guest’s card number masked for display.
  • purchasedItems (List[Object]) – (required) The list of items the guest has purchased as part of this tour. See PurchasedItemInfo for the format of these objects.
"result": "failure"
JSON Parameters:
 
  • result (String) – (required) failure
  • errorCode (String) – (required) The error code of the failure.
  • errorMessage (String) – (required) The human readable error message of the failure.

Reply Objects

ActiveTour

Information about a Tour that is currently active.

JSON Parameters:
 
  • code (String) – (required) Unique code of the tour.
  • label (String) – (required) A displayable label for the tour.
  • startDate (DateTime) – (optional) Date and time that the tour begins if applicable.
  • endDate (DateTime) – (optional) Date and time that the tour ends if applicable.
  • trackedProduct (Object) – (required) The category of items tracked by this tour. See TrackedProdcut for the format of this object.
TrackedProduct

Information about a category of menu items tracked as part of a tour.

JSON Parameters:
 
  • productType (String) – (required) Describes the scope of the tracked category. Valid values are MAJOR_GROUP and MINOR_GROUP.
  • id (String) – (required) The unique category identifier.
  • definition (String) – (optional) An optional product definition.
PurchasedItemInfo

Information about an item purchased as part of a tour.

JSON Parameters:
 
  • itemId (String) – (required) The identifier of this purchased item.
  • itemName (String) – (required) The item name.
  • purchaseDatetime (DateTime) – (required) The date when this item was purchased
  • purchaseStore (Object) – (required) Information about the store where this item was purchased. See StoreInfo for the format of this object.
StoreInfo

Information about a store.

JSON Parameters:
 
  • code (String) – (required) The store’s unique code.
  • name (String) – (required) The name of this location.

Error Codes

The following are the possible codes and messages that can be returned by the Tour Service.

There are other system-level errors which may be returned which are not documented here.

The caller display the returned message end user or, if different wording is desired, can provide their own mapping of code to message.

Code Message
active_tours_failure.general Failed to retrieve active tours error
active_tours_failure.invalid_merchant_id Invalid merchant id
tour_status_failure.general Failed to retrieve tour status
tour_status_failure.invalid_merchant_id Invalid merchant id
tour_status_failure.invalid_tour_code Invalid tour code
tour_status_failure.invalid_card_number Invalid card number
tour_status_failure.user_information_error Unable to find account user information
tour_status_failure.store_locations_error Unable to get store locations
tour_status_failure.store_info_error Unable to get store info
tour_status_failure.purchased_item_error Unable to get purchased item history
tour_status_failure.item_info_error Unable to get purchased item info